Upgrades

Upgrading the platform, and upgrading validator components.

There are two independent upgrade tracks, and it helps to keep them separate.

Track	Changes	Mechanism
Platform	The operator, API, and UI	helm upgrade
Validator components	The Canton participant, validator app, UIs, PQS, Wallet Gateway	Edit the Validator resource

You can upgrade either without the other, within a compatible range.

---

Upgrading the platform

helm upgrade catalyx-canton catalyx/catalyx-canton \
  -n <namespace> -f my-values.yaml

Apply the CRDs first. Helm never upgrades the resources in a chart's crds/ directory. If a release changes the Validator or Application schema and you skip this, new fields will be silently pruned from resources you apply.

kubectl apply -f <chart>/crds

What happens

The operator, API, and UI deployments are rolled. The UI runs multiple replicas by default and has a pod disruption budget, so it stays available. The operator and API run a single replica each — expect a brief interruption while they restart.

Once the new operator starts, it re-reconciles every existing validator. Validators are not restarted unless something they depend on has changed.

Rolling back

helm rollback catalyx-canton -n <namespace>

Rolling back the chart does not roll back the CRDs, because Helm never managed them. If the upgrade introduced schema changes and you roll back the release, the newer CRDs remain in place. The older operator will ignore fields it does not understand.

---

Upgrading validator components

Canton networks upgrade on a schedule, and validators are expected to keep pace with the network's supported protocol versions.

The simple case

If the validator uses spec.network.spliceVersion, one change upgrades the participant, validator app, and both UIs together:

spec:
  network:
    spliceVersion: "0.6.13"

kubectl apply -f my-validator.yaml

The operator rolls each component in turn. Watch the validator's Summary tab as components return to Ready.

Pinned components

A component with its own version ignores spliceVersion. Check for pinned versions before upgrading:

kubectl -n <namespace> get validator my-validator \
  -o jsonpath='{.spec.participant.version} {.spec.validator.version} {.spec.ui.wallet.version} {.spec.ui.cns.version}'

Independently versioned components — PQS and the Wallet Gateway — always need their own version set, and never follow spliceVersion.

Azure KMS bypasses this entirely. When Azure KMS is enabled, the participant runs the KMS-enabled image from spec.kms.azure.preBuiltImage, and both spec.participant.version and spliceVersion are ignored for the participant. Upgrading such a validator means obtaining an updated KMS image. Factor that into your upgrade lead time.

---

Before you upgrade

1

Confirm the target version is supported by the network

Your validator's protocol version must remain compatible with the synchronizer. Check the network's published schedule; for the global Canton Network this is governed by the Global Synchronizer Foundation.

2

Take an identity dump and confirm your database backups

See Identity Dumps & Database Backups. Do this before every version change, not just major ones.

3

Upgrade a non-production validator first

Component versions are per validator, so a lower environment can run the new version while production stays put.

4

Check the release notes

See Release Notes for behaviour changes in the CatalyX release, and the Canton release notes for protocol changes.

---

Domain migrations

When a network performs a domain migration, the migration is coordinated by the network, not by CAT-BM. Two fields participate:

Field	Purpose
spec.network.migrationId	The migration the validator is operating against.
spec.validator.dumpPath	Path to a migration dump, when the migration requires one.

Domain migrations are network-wide events with their own timing and procedure. Coordinate them with IntellectEU support and your sponsoring Super Validator — do not change migrationId speculatively.

---

Version compatibility

The Validator and Application custom resources are served at catalyx.manager.canton/v1alpha1.

Field-level changes may still occur in a future minor release. Treat the CRD schema as stable in shape but not frozen in detail, and read the release notes before upgrading the platform. Keep your Validator resources under version control so a schema change is a reviewable diff rather than a surprise.

Getting help

Upgrade paths, supported version combinations, and migration procedures for a specific deployment are provided by IntellectEU support. See Contact Support.