Upgrade

Use cpctl upgrade to update the Control Panel to a new version in place.

Before you upgrade

Running nodes are unaffected. The upgrade only restarts Control Panel pods. Blockchain node pods in control-panel-deployments continue running throughout.
No downgrades. Before any changes are made, cpctl upgrade runs the following preflight checks: ClusterAccess, ReleaseExists, ReleaseNotPending, VersionCompatibility, NotDowngrade, MaxMajorJump, PendingPods. If any check fails, the upgrade is aborted.
Values are backed up automatically. Before applying changes, your current values are saved to ~/.config/cp-suite/values/pre-upgrade-<release>-<revision>-<timestamp>.yaml. Pass --no-backup to skip this.

cpctl upgrade -v VERSION

Replace VERSION with the target version — see Release notes for available versions.

The upgrade is atomic: if the deployment fails or times out, Helm automatically rolls back to the previous revision. After passing preflight checks and backing up your values, cpctl upgrade computes a server-side diff and presents an upgrade plan before prompting for confirmation:

╭────────────────────────────────────────────────────────────────────────╮
│                              Upgrade Plan                              │
├────────────────────────────────────────────────────────────────────────┤
│  Release:   cp (namespace: control-panel)                              │
│  From:      cp-distributed v1.7.1 (rev 1)                              │
│  To:        cp-distributed v1.8.0                                      │
│  Values:    preserved (backed up)                                      │
│  Mode:      atomic (auto-rollback on fail)                             │
│  Backup:    /root/.config/cp-suite/values/pre-upgrade-cp-1-<timestamp>…│
├────────────────────────────────────────────────────────────────────────┤
│  Changes:                                                              │
│    ~ Deployment/cp-cp-ui (containers, metadata.labels, pod.labels)     │
│    ~ Deployment/cp-cp-deployments-api (containers, initContainers, …)  │
│    + Job/cp-temporal-schema-2                                          │
│    - Job/cp-temporal-schema-1                                          │
│    ... and more                                                        │
╰────────────────────────────────────────────────────────────────────────╯

Proceed with upgrade? [y/N]:

On success:

✓ Upgrade to v1.8.0 completed (revision 1 → 2)

After a successful upgrade, a journal is written to your config directory for auditability.

Upgrade flags

Flag	Description	Default
`-v, --version`	Chart version to upgrade to (required)	—
`-f, --values`	Path to custom values file	—
`--set key=value`	Set Helm values (repeatable)	—
`-s, --storage-class`	Storage class for persistent volumes	—
`--chart-registry`	OCI registry URL	Public CP registry
`--show-diff`	Show full resource-level diff (not just summary)	`false`
`--no-diff`	Skip diff preview	`false`
`--no-backup`	Skip values backup before upgrade	`false`
`--ignore-preflight-errors`	Comma-separated preflight check names to skip; use `all` to skip all	—
`--preflight-timeout`	Preflight phase timeout	`1m0s`
`--skip-version-check`	Bypass version compatibility validation	`false`
`--reset-values`	Reset values to chart defaults, discarding current values	`false`
`--force`	Force resource update through delete/recreate. Causes brief service disruption. Use only when a normal upgrade fails due to immutable field changes.	`false`
`--timeout`	Helm upgrade timeout	`15m0s`
`-y, --yes`	Skip confirmation prompts	`false`

Troubleshooting

If an upgrade fails, check the upgrade journal for a detailed error log:

cat ~/.config/cp-suite/upgrade-journal.jsonl
# or inspect the pre-upgrade backup
ls ~/.config/cp-suite/values/pre-upgrade-*.yaml

To preview what an upgrade would change without applying anything:

cpctl upgrade -v VERSION --show-diff --dry-run

Next steps

Uninstallation — Remove Chainstack Self-Hosted from your cluster
Installation — Reinstall from scratch

Self-Hosted

Installation

Node management

Help

Upgrade

Before you upgrade

Upgrade

Upgrade flags

Troubleshooting

Next steps

​Before you upgrade

​Upgrade

​Upgrade flags

​Troubleshooting

​Next steps

Before you upgrade

Upgrade

Upgrade flags

Troubleshooting

Next steps