> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/upgrades.md).

# Upgrades

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

<table><thead><tr><th width="230">Track</th><th width="200">Changes</th><th>Mechanism</th></tr></thead><tbody><tr><td><strong>Platform</strong></td><td>The operator, API, and console</td><td><code>helm upgrade</code></td></tr><tr><td><strong>Validator components</strong></td><td>The Canton participant, validator app, UIs, PQS, Wallet Gateway</td><td>Edit the <code>Validator</code> resource</td></tr></tbody></table>

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

***

## Upgrading the platform

```bash
helm upgrade catalyx-canton catalyx/catalyx-canton \
  -n catalyx-system -f my-values.yaml
```

{% hint style="danger" %}
**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.

```bash
kubectl apply -f <chart>/crds
```

{% endhint %}

### What happens

The operator, API, and console deployments are rolled. The console 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

```bash
helm rollback catalyx-canton -n catalyx-system
```

{% hint style="warning" %}
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.
{% endhint %}

***

## 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:

```yaml
spec:
  network:
    spliceVersion: "0.6.13"
```

```bash
kubectl apply -f my-validator.yaml
```

The operator rolls each component in turn. Watch the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary.md) tab as components return to `Ready`.

### Pinned components

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

```bash
kubectl -n catalyx-system 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`.

{% hint style="warning" %}
**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.
{% endhint %}

***

## Before you upgrade

{% stepper %}
{% step %}
**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.
{% endstep %}

{% step %}
**Take an identity dump and confirm your database backups**

See [Identity & Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-and-backups.md). Do this before every version change, not just major ones.
{% endstep %}

{% step %}
**Upgrade a non-production validator first**

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

{% step %}
**Check the release notes**

See [Release Notes](/catalyx-blockchain-manager/canton-network/version-2.0/release-notes.md) for behaviour changes in the CatalyX release, and the Canton release notes for protocol changes.
{% endstep %}
{% endstepper %}

***

## Domain migrations

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

<table><thead><tr><th width="290">Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>spec.network.migrationId</code></td><td>The migration the validator is operating against.</td></tr><tr><td><code>spec.validator.dumpPath</code></td><td>Path to a migration dump, when the migration requires one.</td></tr></tbody></table>

{% hint style="warning" %}
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.
{% endhint %}

***

## Version compatibility

{% hint style="info" %}
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.
{% endhint %}

## Getting help

Upgrade paths, supported version combinations, and migration procedures for a specific deployment are provided by IntellectEU support. See [Contact Support](/catalyx-blockchain-manager/canton-network/version-2.0/support-and-resources.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/upgrades.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.