Updating CloudPeek

Updating is an in-place upgrade from a newer installer tarball. CloudPeek does not fetch new versions on its own, so an update always starts with a new bundle from your CloudPeek contact.

Before you start

Verify and extract the new tarball's signature exactly as described in Prerequisites. Never point cpk update at a tarball whose signature you have not checked.

Run the update

From your existing install directory, point cpk at the new tarball:

cd cloudpeek
./cpk update --new /path/to/cloudpeek-installer-v<version>-<platform>-<arch>.tar.gz

--new is required. Add -y to skip the confirmation prompt for unattended runs.

What update preserves, and what it replaces

Your data is kept. update never runs docker compose down, so Postgres, Zitadel, Redis and Neo4j hold their volumes and stay up through the upgrade.

Your files are not. Every entry that exists in the new tarball replaces the copy in your install directory, and the cpk binary itself is swapped at the end. Anything the tarball does not ship survives, which covers .secrets/, volumes/ and any extra files you added yourself.

Steps that can be re-run afterwards

update finishes with two follow-up steps that are allowed to fail without failing the upgrade, because neither decides whether the new version runs. If either reports a problem, the upgrade itself succeeded and you simply run the command it names.

The identity-provider role sync. If the update reports that it did not run, repair the role catalogue with ./cpk sync-zitadel-roles. That happens in two cases: the sync failed after its retries, or it was skipped because the Zitadel environment variables could not be read.

The migration step. After swapping the binary, update runs ./cpk migration to apply the one-time reconciliation steps introduced since the version you were on. If that step reports a failure, run it yourself with the version the update prints:

./cpk migration --last-version 0.8.34

Migrations are idempotent, so re-running is safe. It applies only the steps introduced between the version you give it and the installed version, which means a repeat run does nothing and a version at or above the current one reports that there is nothing to do.

Related

• Export and Import: back the instance up before a major upgrade.
• Prerequisites: verifying the signature of the new bundle.
• cpk Command Reference: every command the installer supports.