Skip to main content

Upgrading

Move a running install to a newer release. The data and the namespaces stay.

⚠️ Back up first — Take a backup before any upgrade. See Backup & restore. Some secrets are write-once and an upgrade does not change them. See Configuration.

⚠️ Never run an install.octostar.com script over an existing install. It deletes /opt/octostar, and your local-env.yaml with it.

Online upgrade​

The steps assume the installer is in /opt/octostar.

1. Move the current install aside​

BACKUP=/opt/octostar-$(date +%Y%m%d-%H%M%S)
sudo mv /opt/octostar "$BACKUP"

Your local-env.yaml is in $BACKUP. It is the only copy of your configuration.

2. Download the latest release​

curl -fsSL https://install.octostar.com/install-octostar-raw.sh | bash -s -- --nightly

--nightly is the current build of main. Two sites that upgrade on different days can get different builds. Add --version to print the build without the download.

3. Copy over local-env.yaml​

sudo cp -p "$BACKUP/local-env.yaml" /opt/octostar/local-env.yaml
sudo chown -R "$USER" /opt/octostar

Check the file:

  • update-existing.sh deploys exactly what the file says. If someone changed the cluster by hand, put that change in the file now.

  • Compare the templates, and set the new settings that you need:

    diff "$BACKUP/local-env.template.yaml" /opt/octostar/local-env.template.yaml

4. Run the update​

cd /opt/octostar
./bin/update-existing.sh --context <context-name>

📝 The script can stop and ask you to type yes. It does this before a PostgreSQL major upgrade (an outage while it runs), while MinIO is still present, before a move to external S3, and before it reduces replicas. Do not run it unattended.

5. Verify​

The update uses the release's own kubectl. To run it from your shell, put the release's tools on your PATH first, in /opt/octostar (see Prerequisites):

export PATH="$PWD/bin/tools/$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/'):$PATH"
kubectl --context <context-name> get pods -n octostar-main

All pods must be Running and Ready. Then remove $BACKUP, and keep a copy of its local-env.yaml.

Air-gapped upgrade​

Use the same update-existing.sh. It reads offline and chartRepoBase from local-env.yaml.

  1. Mirror the images and charts of the new release. See Air-gapped installation.
  2. Put the octostar-singlenode files of the new release on the install host, and keep the old directory as in step 1. Copy your local-env.yaml into the new directory. Keep offline: true, chartRepoBase and the pinned PostgreSQL images. If the new release has other PostgreSQL images, change the pinned values.
  3. Run ./bin/update-existing.sh --context <context-name>.

Rotate the platform keys​

Each install has its own EC private key. It signs every session and encrypts stored settings, mount credentials and watchers. Never share a key between installs. To replace it:

⚠️ Save the old key first — The backup bucket keeps only one copy of the key. After a rotation, only the old key decrypts the data in an older backup. If you might restore one, save the old key:

kubectl --context <context-name> -n octostar-main get secret os-ec-priv-key-secret \
  -o jsonpath='{.data.OS_EC_PRIV_KEY}' | base64 -d > old-ec-key   # keep it safe

To restore such a backup, set the old key as octostar.ecPrivateKey in local-env.yaml, and run restore-install.sh --keep-local-env.

./bin/update-existing.sh --context <context-name> --rotate-platform-keys

The script asks first. --yes skips the question. During the rotation:

  • Every user is logged out.
  • API tokens that you hold outside the install stop working.
  • The API, its workers and the scheduler restart.

If the update stops, run a plain update-existing.sh to finish it. Fix the items that the log lists as failed. Do not leave the rotation unfinished. If the script refuses to start, pin a newer API in versions.octostarApi, run a plain update, and try again.

If it fails​

  • Apps did not come back. An update redeploys the bundled apps. A failure there is a warning. When the upgrade-apps-job no longer runs, sync only this step, with the release's own helmfile and helm on your PATH (see Prerequisites):

    helmfile --kube-context <context-name> -f ./helmfile-apps-upgrade.yaml.gotmpl sync

    If it says another operation ... is in progress, run helm --kube-context <context-name> -n octostar-main uninstall octostar-apps-upgrade and sync again. An app that the log names as not back is down. Deploy it again from the Apps panel. Set octostar.upgradeApps: false to skip this step.

  • UPGRADE FAILED ... conflict with "kubectl-patch". Someone changed a field by hand. Put the field back, or let the chart win for that release, with the release's own helmfile and helm on your PATH (see Prerequisites):

    helmfile --kube-context <ctx> -f <helmfile in the error> -l name=<release> \
      --args=--force-conflicts sync

    Then run update-existing.sh again. Make future changes in local-env.yaml.

  • The update stops for lack of disk. A new geocoding index needs room for the old and the new index. Add disk, or set photon.initDownload.source: url. See Storage and S3.

  • ImagePullBackOff. The image is not in your registry, or its registry host was not rewritten. On an air-gapped install, see Air-gapped installation.

  • CrashLoopBackOff. Read the pod logs: kubectl logs -n octostar-main <pod>.