Skip to main content

Upgrading

Octostar upgrades reuse the same Helmfile machinery as a fresh install — the update scripts re-sync the helmfiles against newer chart/image versions (versions.yaml) without recreating namespaces or re-running first-install-only steps.

⚠️ Back up first — Take a backup/snapshot of your stateful components (PostgreSQL, ClickHouse, OpenSearch, object storage) before any upgrade. Also note that several secrets are write-once at first install and are not changed by upgrades — see Configuration.

Online upgrade​

./bin/update-existing.sh --context <context-name>

This is pure orchestration: it helmfile syncs the same helmfiles install.sh does, picking up the chart/image versions currently pinned in versions.yaml. Update your checkout (e.g. git pull to the target release) before running.

Typical flow:

cd octostar-singlenode
git fetch && git checkout <target-release>
# review changes to versions.yaml / local-env requirements
./bin/update-existing.sh --context <context-name>
kubectl get pods -n octostar-main

Air-gapped upgrade​

Use offline-update-existing.sh when Octostar is already installed and you want to upgrade it air-gapped. It is the offline counterpart to update-existing.sh, the same way offline-installer.sh is the counterpart to install.sh.

./bin/setup-local-env.sh                 # only if local-env.yaml doesn't exist yet
./bin/offline-update-existing.sh --context <kube-context> [ ...same flags as update-existing.sh... ]

What it does:

  1. Runs the identical air-gap repo preparation that offline-installer.sh uses (offline_patch_repo from lib/offline-patch.sh): normalises local-env.yaml, checks required tools, resolves and exports OCTOSTAR_CHARTS_OFFLINE, runs patch_charts_offline_helmfiles.py (every remote chart ref → local .tgz, repositories: []), and applies the one-time helmfile marker-patches.
  2. Runs bin/update-existing.sh unchanged.

Why it's simpler than offline-installer.sh: update-existing.sh has no Docker Hub/OCI connectivity probe, does not create namespaces, and does not apply the ClickHouse CHI — so the offline wrapper needs no helm shim and no temp-patched copy of the script. The only air-gap work is the shared repo prep.

Requires (alongside the wrapper in bin/): update-existing.sh, patch_charts_offline_helmfiles.py, and lib/offline-patch.sh. Same prerequisites as offline-installer.sh except namespace pre-creation and ClickHouse-CHI handling (the install already exists). local-env.yaml, the CLI tools, and the vendored charts-offline/ tree are still required.

  1. Request a new bundle from Octostar for the target release, so the image set and charts-offline/ match the new versions.yaml (see Air-gapped installation).
  2. push-images.sh with the new image set from the bundle.
  3. ./bin/offline-precheck.sh — catch bundle/repo drift before touching the cluster (exit 0 expected).
  4. ./bin/offline-update-existing.sh --context <ctx>.

The same patch-application summary described for installs is printed on every upgrade — if offline-precheck.sh reports missing(fatal), the bundle is inconsistent; contact Octostar for a corrected bundle rather than forcing the upgrade.

Verifying an upgrade​

kubectl get pods -n octostar-main
kubectl rollout status deploy/<deployment> -n octostar-main   # for a specific workload

Watch for pods stuck in ImagePullBackOff (registry/Gatekeeper issue on air-gap — see Air-gapped installation) or CrashLoopBackOff (check logs).