Skip to main content

Air-gapped installation

Install Octostar in a cluster with no route to the internet. It is the same bin/install.sh as an online install, with offline: true in local-env.yaml.

What you need​

  • A private container registry that all nodes can reach. It must hold every image of the release.
  • A Helm chart repository inside your network. It must hold every chart of the release. It must be a classic HTTP repository (made with helm repo index), not an OCI registry, and it must be flat.
  • An admission mutator in the cluster that rewrites the registry host of each image to your registry. For example, OPA Gatekeeper with an AssignImage mutation. Octostar does not install one.
  • On the install host: kubectl, helm, helmfile and yq. The release files carry them (v2.0.9 and later), and the installer uses those. For an older release, install them yourself.
  • The octostar-singlenode files of the release, and a kube context for the cluster.

📝 Ask your Octostar contact how you get the image list and the charts for your release. versions.yaml gives the version of each one.

Steps​

1. Mirror the images and the charts​

Copy every image into your registry, and every chart into your chart repository. Keep the image paths. For example, docker.io/octostar/photon-data becomes <registry>/octostar/photon-data.

2. Set up the registry rewrite​

Install the mutator. Pull one pod from your registry to test it.

3. Write local-env.yaml​

cp local-env.template.yaml local-env.yaml

Set at least these values:

offline: true
chartRepoBase: "http://charts.example.internal:8879"

postgresql:
  imageName: "<registry>/cloudnative-pg/postgresql:16.4"
  operatorImageRepository: "<registry>/cloudnative-pg/cloudnative-pg"
  operatorImageTag: "1.24.1"
  operatorImagePullPolicy: Always
  • Write offline as a bare true. yes and on are refused.
  • Use the PostgreSQL image and operator tags of your release. The example tags are not a promise.
  • You do not need a Docker Hub token.
  • The install sets bigData: "none". You cannot change it offline.
  • Set ingress.controllerImageDigest only if your mirror kept the upstream digest.
  • A Grafana plugin that you add with grafana.plugins must be written as <zip URL>;<plugin id>, on a server that the cluster can reach.

See Configuration for the domain and the certificate. The map tiles and the geocoding index are large. Leave them off unless you need them. See Storage and S3.

4. Install​

./bin/install.sh --context <context-name>

The installer creates its namespaces. If you made them first, it keeps them. Use --dry-run to preview.

5. Verify​

The install uses the release's own kubectl. To run it from your shell, put the release's tools on your PATH first, from the directory the release is in (see Prerequisites):

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

Open https://home.<domain> when the pods are ready.

If it fails​

  • ImagePullBackOff: the mutator did not rewrite the image, or the registry does not hold it. Read the image name in kubectl describe pod <pod>.
  • A chart error in the first minutes: chartRepoBase is wrong, or the repository lacks the chart.
  • A PostgreSQL pod that restarts in a loop: the pinned PostgreSQL image differs from the image that the mutator admitted. Fix the postgresql.* values.

Upgrade and restore​

  • Upgrade: mirror the new release, then run update-existing.sh. See Upgrading.
  • Restore: use restore-install.sh --offline. See Backup & restore.