Upgrade

Use kindo upgrade to preview and apply a Self-Managed Kindo release.

Release cadence and versioning

Kindo ships monthly releases with calendar versions such as 2026.09.<n>.

Run the upgrade

Run every kindo upgrade command from the directory holding install-contract.yaml and environment-bindings.yaml.

Preview the upgrade

kindo upgrade --version <target> --plan

The plan leaves your deployment unchanged. It shows what you need to check or act on: the prerequisite and cluster checks, chart availability at the target version, a reminder to back up after the upgrade when it generates new credentials, the running Helm values the upgrade resets (see Helm customizations across upgrades), and configuration you must provide. Add --verbose to also see what the upgrade handles on its own, such as environment variable and feature flag changes and the upgrade steps.

The command exits non-zero when something blocks --apply: a missing operatorEmail, charts missing from the registry, an unwritable contract file, or required values missing from your secrets store. Fix every blocking issue and run the plan again. Save the plan output as a record.

Apply the upgrade

kindo upgrade --version <target> --apply

Optional flags:

Flag	Purpose
`--dry-run`	Preview Helm diffs.
`--verbose`	Show raw output.
`--readiness-timeout <seconds>`	Set how long to wait for the API to come up. The default is 600 seconds; 0 skips the wait.

If the target release’s infrastructure checks fail, the upgrade stops before changing any release.

When the install needs its first superadmin, the upgrade creates the account for operatorEmail and prints its key once. Store the key; it is not shown again. If a superadmin already exists, it confirms this with already bootstrapped.

Success prints Upgrade to <version> complete!. The Superadmin: line says whether the account was created or already existed. If it says not independently verified, check the account status:

kindo status

Once the API is up on the target version, the install records that version, including when a later part of the upgrade fails.

If the run completes with warnings, fix the reported cause and run the command named in the warning:

kindo install --step integrations

Or, for a feature flag warning:

kindo install --step sync-flags

If superadmin setup fails, the run prints Upgrade to <version> did not complete: superadmin-bootstrap failed. Recover by fixing the cause and running these commands in order:

kindo install --step superadmin-bootstrap
kindo install --step integrations

Helm customizations across upgrades

Keep Helm customizations in kindo config helm-override to preserve them through every upgrade. The upgrade applies the target release’s values plus your Helm overrides. A value set another way, such as through helm upgrade --set, stops applying at the next upgrade.

Both --plan and --apply (before it starts making changes) list, under Helm Values, each running value the target release resets that you may have set. Each entry shows the release, path, and running value. Earlier releases’ defaults are counted rather than listed; add --verbose to list them. Credential values appear as (hidden). The list excludes secret and environment blocks, global and ingress values, and Kindo image tags, which Kindo sets.

To keep a value you set on purpose, such as replica counts, resources, or node placement:

Save it as a Helm override before running --apply:
Terminal window
```
kindo config helm-override set <release> <path>=<value>
```
Run --plan again to review the result.

The upgrade applies the saved override.

Ingress comes from the install contract on every upgrade. Change hosts or edge settings in the contract. Per-release ingress.annotations values saved with kindo config helm-override survive upgrades. Direct edits to the live Ingress object are replaced at the next upgrade.

Per-application secrets on upgrade

On the default Kubernetes secrets backend, kindo upgrade regenerates each application’s secrets from the saved configuration. Overrides set with kindo config override set and values set in the contract survive the upgrade unchanged.

If the target version requires a secret that you supply, such as an OAuth client secret, the Kubernetes backend prompts for it before continuing. The value is saved and reused on subsequent upgrades.

External secrets store

Values in an external secrets store take precedence. Before making changes, the upgrade checks that every required value is available from the store or supplied by Kindo. If values are missing, add them to the store and run the upgrade again. Supply new keys directly in the external store before upgrading; prompts for new keys are available only on the Kubernetes backend.

Upgrade without local config files

When install-contract.yaml or environment-bindings.yaml is missing from the current directory, the CLI asks Reconstruct from live deployment?.

Preview the files to be reconstructed, if needed:
Terminal window
```
kindo config reconstruct --dry-run
```
This prints both files and leaves your files and deployment unchanged.
Confirm reconstruction when prompted during the upgrade. The CLI writes both config files to the current directory using the live cluster.
Fill in SMTP and operator details. If SMTP settings are missing, the CLI stops and asks you to fill in smtp in the contract, then run the upgrade again. In an interactive terminal it prompts for operatorEmail; for unattended runs, set it in the contract.
Replace the admin database credential placeholders in the generated bindings with real admin credentials before upgrading to a release that adds a database.

If an upgrade was interrupted

Check cluster health.
Terminal window
```
kindo doctor
```
An interrupted upgrade can leave Helm releases locked in a pending state. Doctor reports these as critical, and --apply refuses to start while they remain.
Wait for any active upgrade session to finish. If another session is still running the upgrade, let it complete before repairing releases.
Repair locked releases.
Terminal window
```
kindo doctor --fix
```
After you confirm, this rolls each locked release back to its last deployed revision. A release that has never deployed stays in place.

Run the upgrade again.

kindo upgrade --version <target> --apply

Rollback

To return to the previous release, restore the pre-upgrade configuration backup and database snapshots onto an empty cluster:

Reinstall the previous release’s CLI from the artifact you kept before upgrading.
Prepare an empty cluster with all Kindo components absent.
Restore the pre-upgrade database snapshots at their original hostnames.
Restore the configuration bundle with that CLI, following the restore steps in Back up and restore. Keep the original database hostnames in environment-bindings.yaml.

Pre-upgrade checklist

Complete every item before applying an upgrade:

Check	How
Configuration backup taken	Run `kindo config backup` and store the encrypted bundle and passphrase.
Database snapshots current and restorable	Snapshot every Postgres instance Kindo uses.
Cluster health clear	Resolve every critical finding from `kindo doctor`.
Upgrade plan clear	Run `kindo upgrade --plan`; resolve every blocking issue and confirm a successful exit.
Helm customizations saved	Keep required values in `kindo config helm-override`.
CLI matches the target release	Check `kindo --version`.
Registry egress open	Allow access to `registry.kindo.ai`.
Maintenance window scheduled	Reserve time for the upgrade and smoke tests.
Other configuration operations finished	Wait for every other `kindo install`, `kindo upgrade`, or `kindo config apply` session to finish.

Post-upgrade checklist

Check	How
Target version and healthy releases	Check `kindo status`.
All pods Ready	Run the pod health check.
Cluster health clear	Resolve every critical finding from `kindo doctor`.
Smoke tests pass	Follow Configure & Validate.
Observability at baseline	Check dashboards for expected error rates, latency, and resource use.

Next steps

OperateManage the install and check its health.

Upgrade from 2026.07 to 2026.09Prepare, upgrade, restore SSO, and roll back.