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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.chainstack.com/feedback

```json
{
  "path": "/docs/self-hosted/upgrade",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# 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