Skip to content

Upgrades

Three things get upgraded, each with its own procedure.

What How
Tenantry Re-run scripts/install.sh with --version
Teleport Change the pinned image of your cluster, then align Tenantry
Steward consoles The console's upgrade.sh, driven from Tenantry

Upgrade Tenantry

install.sh is re-runnable. Running it again with the same --name and --dir keeps everything: .env (admin password hash, session secret, secrets encryption key), the /data volume, the certificate, and the Machine ID identity. No bot token is needed again.

  1. Take a backup.

  2. Update the installer and run it with the release you want:

    cd tenantry
git pull
sudo scripts/install.sh --name acme --public-url https://tenantry.acme.ch \
  --teleport-local auto --expose cloudflare-tunnel \
  --version 1.3.0

    Repeat the same options you used at install (the guided mode prints them at the end of an install). --teleport-local auto finds the local Teleport again.

  3. Check Security (Machine ID renewed) and Client proxies (fleet readable).

Notes:

  • The image comes from Docker Hub (verttigo28/tenantry:<version>, mirrored on ghcr.io/verttigo28/tenantry). Pass --version to change the release: without --version, --image or --build, a re-run keeps the image already installed (pinned by digest), and a first install refuses to start (latest is never assumed). With cosign installed the signature is verified (--require-signature makes it mandatory).
  • --image REF uses a specific image or digest. --build builds from the checkout.
  • The installer rewrites the compose files in <dir>. Do not edit them by hand.
  • Verify the image before you install: Verify the image.
  • Changing the Tenantry version never changes your Teleport. The bundled tctl (18.11.1) works with any 18.x cluster; for another major version use --build --teleport-version X.Y.Z.
  • Installed with a new Teleport cluster bundle? The same, from the bundle: sudo tenantry/scripts/install.sh --name <name> --public-url https://<tenantry name> --teleport-local auto --expose proxy --version <x.y.z>.

Do not use --reset-secrets for an upgrade

--reset-secrets regenerates the admin password, the session secret and the secrets encryption key. Console tokens and alert channel secrets stored in /data become unreadable and must be entered again.

Upgrade Teleport

  1. Read the Teleport release notes. Never skip a major version.
  2. Back up (the bundle has ./backup.sh).
  3. Change the pinned image tag in the cluster's compose.yml, then docker compose pull && docker compose up -d.
  4. Keep Tenantry in line. tctl and tbot should match the cluster. After a minor or patch upgrade, re-run install.sh --teleport-local auto: it detects the new version and uses it for the tbot image. After a major upgrade, rebuild with --build --teleport-version X.Y.Z so the embedded tctl matches.
  5. Agents (client proxies) must not be newer than the cluster. See the version gap on Client proxies.

Upgrade Steward consoles

Set a target version and let Tenantry show which consoles are behind and generate the exact commands per host: Upgrading Steward consoles. For a single console, see the operations table in Publish Steward.