Install

Docs / Upgrade

Upgrade

0.0.1 is the first release, so there is nothing to upgrade from yet. This guide describes how every later release is installed over a running one, and what can and cannot be rolled back.

Before you start

  1. Read the release notes of every release between yours and the target. They state whether the release changes storage images, storage formats or the console schema in a way that cannot be rolled back.
  2. Download and verify the new bundle (verify.md). Keep the old bundle and its release.env: you need them to roll back.
  3. Take a management database backup if you run the console, and refresh your exported platform Secrets (backup-and-restore.md).
  4. Upgrade outside peak hours. While the controller restarts, running databases keep serving but suspended branches cannot wake. To avoid wake delays, raise suspendAfterSeconds on critical branches beforehand.

Upgrade the platform

Use the new bundle with the same settings you installed with:

cd skeladb-<new version>
set -a; . ./release.env; set +a
export SKELA_KUBE_CONTEXT='<your context>'   # plus your other install variables
./install.sh apply

What happens:

  • The Branch resource definition is updated. Fields are only ever added, so existing branches stay readable.
  • The controller is replaced: the old one finishes in-flight work and backups, releases ownership, and the new one takes over. The proxy rolls one replica at a time; clients on a replaced replica reconnect.
  • Running databases move to the new PostgreSQL image gradually, one at a time by default (SKELA_IMAGE_ROLLOUT_MAX), each restarting once. A suspended branch starts on the new image at its next wake. The branch condition ImageCurrent shows RolloutPending, Rolling or Current. If a new image never becomes ready, the rollout stops after that branch.
  • The controller and the PostgreSQL image must come from the same release. A mismatched image stops before touching data and the branch reports ComputeProtocolMismatch; install the matching image to recover.

Then check: kubectl -n skela get branches shows every branch Running or Suspended with ImageCurrent=True, an application can log in and read recent rows, and one new test branch can be created and deleted.

Object storage pools

Each project’s storage pool records the page server, WAL and PostgreSQL images it was created with, and the controller refuses to change them implicitly. When a release changes those images, its notes include the pool procedure, which follows this shape:

  1. Scale the controller to zero and wait until it has released ownership.
  2. For each project, update the image fields in its skela-pool-<project> ConfigMap to the new digests, leaving every other field as it is.
  3. Replace the three WAL nodes one at a time, waiting for each to rejoin the quorum before the next. Stop at the first error.
  4. Replace the page server, seed and redo images if the notes say so.
  5. Start the controller and confirm every pool reconciles without an input mismatch and keeps its disks.

Never delete a pool ConfigMap, the controller Lease or a capacity record to get past a refusal.

Upgrade the console

set -a; . ./release.env; set +a
cloud/render.sh apply

It deletes the previous migration Job, runs the new one and waits. If the migration fails it prints the Job’s log and stops; the running console keeps working, because migrations only add to the schema. Fix the cause and run it again. After the migration it rolls out the API, worker and console.

Roll back

Console. Load the previous release’s release.env and run cloud/render.sh app | kubectl apply -f -. Do not run the previous release’s migration: older releases work with a newer schema. A release whose notes declare a contract migration (one that removes or narrows something) cannot be rolled back past; restore the management database backup taken before it instead.

Platform. Run the previous bundle’s ./install.sh apply. This is safe only when the release notes say the new release wrote no new storage format. Some changes are one-way: an older WAL service cannot read a newer WAL archive format, and an older page server cannot read a newer catalog format. For those, the way back is a restore into an isolated destination from a recovery point taken before the upgrade, not an image change.

PostgreSQL major versions never change in place. Create a new project on the new major, copy the data with Import & migrate in the console (import from a database URL), check it, then switch your application over. The source is left untouched.

Certificates and trust

Upgrades never replace your certificate authority. Leaf certificates renew by themselves; replacing a CA is a separate procedure in rotate-keys-and-certificates.md.