Control-plane upgrades

Prepare, apply, validate, and recover from an Infra installation upgrade.

Control-plane upgrades change Infra's management services and database schema. Use the release manifest to coordinate control-plane, agent, and Connector compatibility.

PrepareCopy link

Read the target release's upgrade path and prerequisites. Confirm supported source versions, database version, disk space, agent compatibility, and any required intermediate release. Do not skip a required migration step.

Create and verify a control-plane backup. Record the current release, deployment configuration, active operations, and rollback constraints. Pause scheduled maintenance and automatic rebalancing for the upgrade window.

Drain management workCopy link

Stop accepting new maintenance plans and wait for critical operations to finish or reach a documented safe boundary. A worker shutdown waits up to the configured shutdown timeout. Work that outlives that timeout must be reconciled after restart.

Stopping the API does not stop every guest. Workload continuity still depends on healthy compute, storage, and network services. Avoid upgrading those dependencies in the same step unless the release procedure requires it.

Apply a Compose upgradeCopy link

On the control-plane host, open the verified target release-bundle directory. Preserve persistent paths and secret references. Complete these steps in the order required by its release manifest:

1. Check release compatibility and prerequisites:

   ./infra-admin upgrade check --release-manifest release-manifest.json

2. Prepare the installation for the upgrade:

   ./infra-admin upgrade prepare

3. Apply the required database migrations:

   ./infra-admin database migrate

4. Start the upgraded services using the retained configuration:

   docker compose --env-file infra.env up -d

5. Inspect their health:

   ./infra-admin health check

Stop at a failed command and resolve its reported condition before continuing. A failed schema migration prevents the new service from becoming ready. Inspect the migration result before repeating it or starting another version.

Apply an HA upgradeCopy link

Run the coordinated schema job once, then roll API and worker replicas according to the supported compatibility window. Readiness checks must prevent an incompatible replica from receiving normal traffic.

Mixed versions are permitted only within the release's declared compatibility range. A successful container start is not evidence that the database and agents are compatible.

ValidateCopy link

Check sign-in, organization and project lists, API reads, operation polling, agent reconnects, secret decryption, metrics ingestion, and backup destination access. Create and remove a test droplet through the intended network and storage policy.

Review operations that were active before the upgrade. Wait for reconciling work to reach an authoritative outcome before resuming scheduled automation. Follow Agent updates separately when new node software is required.

Rollback and recoveryCopy link

A release that changes persisted state can make direct binary rollback unsupported. Use the manifest's rollback procedure. If restoration is required, recover the coordinated backup and reconcile infrastructure changes made after its capture.

Do not start an older control plane against a schema it does not support. Retain the failed release's logs and migration output for diagnosis without exposing database credentials or key material.