Upgrade

Upgrade Chainstack Self-Hosted to a new version using cpctl

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.

Upgrade

cpctl upgrade -v VERSION

For example:

cpctl upgrade -v v1.4.6

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.4.6 (rev 1)                              │
│  To:        cp-distributed v1.5.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.5.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