> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade

> Upgrade your Chainstack Self-Hosted installation to the latest version using cpctl, with pre-upgrade checks and rollback guidance for safe updates.

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

```bash theme={"system"}
cpctl upgrade -v VERSION
```

<Note>
  Replace `VERSION` with the target version — see [Release notes](/docs/self-hosted/release-notes) for available versions.
</Note>

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:

```text theme={"system"}
╭────────────────────────────────────────────────────────────────────────╮
│                              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:

```text theme={"system"}
✓ 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:

```bash theme={"system"}
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:

```bash theme={"system"}
cpctl upgrade -v VERSION --show-diff --dry-run
```

## Next steps

* [Uninstallation](/docs/self-hosted/uninstallation) — Remove Chainstack Self-Hosted from your cluster
* [Installation](/docs/self-hosted/installation) — Reinstall from scratch