Skip to content

Upgrade and migration

Upgrade the operator chart and the Garage image as separate changes when possible. Read the release notes and compatibility matrix before changing a major behavior, API shape, storage template, or reserved environment.

Chart upgrade

helm repo update  # if using a local repository mirror
helm upgrade garage-operator \
  oci://ghcr.io/rajsinghtech/charts/garage-operator \
  --version 0.8.2 \
  --namespace garage-operator-system \
  --reuse-values
kubectl -n garage-operator-system rollout status \
  deployment/garage-operator-controller-manager --timeout=180s

For a new values file, render and inspect first:

helm template garage-operator \
  oci://ghcr.io/rajsinghtech/charts/garage-operator \
  --version 0.8.2 --namespace garage-operator-system > rendered.yaml

CRDs are upgraded separately by Helm's CRD mechanism. Back up custom resources before a release that changes conversion or schema behavior.

Ingress exposure is opt-in (chart ingress.enabled)

Releases before the ingress.enabled value always granted the operator create/delete/patch/update/watch on networking.k8s.io/ingresses cluster-wide and always watched Ingresses. Now this is controlled by the chart value ingress.enabled (default false, like gatewayAPI.enabled), which renders the --enable-ingress flag (ENABLE_INGRESS) and the Ingress RBAC rules, and registers the Ingress watch only when set.

If any GarageBucket sets spec.websiteExposure.ingress, upgrade with --set ingress.enabled=true (or add ingress: {enabled: true} to your values file). Otherwise the bucket reports WebsiteExposed=False with reason IngressDisabled; Ingresses created by the earlier release are left in place (they keep serving and are still garbage-collected with their bucket) but are no longer reconciled or cleaned up by the operator until you enable the value. Installs that do not use Ingress exposure need no change and now run without any Ingress RBAC. --reuse-values upgrades from a release without the value render the new default (disabled), so pass --set ingress.enabled=true explicitly if you need it.

Raw-manifest installs (install.yaml or the config/default kustomize base) have no ingress.enabled value: they ship the Ingress RBAC rule but start the manager without --enable-ingress (and without --enable-gateway-api), so Ingress exposure stays off until you add the flag. See Raw manifests: website exposure flags for a copy-paste kubectl patch and kustomize patch.

Garage image upgrade

Pin an image explicitly and let the operator coordinate identity-bearing rollouts:

spec:
  image: dxflrs/garage:v2.4.1@sha256:9c96caa2612d3411acc5b0e6701fb238dbfba33e533a6d7d3d811a4b12d0d020

Do not change the image, volume topology, replica count, and replication factor in one unreviewed edit. Watch StorageRolloutReady, StorageTopologyReady, NodeLocalPoolsReady, and the Garage health conditions after each change.

v1beta1 to v1beta2

Existing v1beta1 GarageCluster resources continue to work through conversion. New manifests should move from:

spec:
  replicas: 3
  gateway: false

to:

spec:
  storage:
    replicas: 3

For a unified cluster, declare both storage and gateway in v1beta2. Use the v1beta2 endpoint for tools that need gateway tiers, node-local pools, or conversion-preserved fields. See API versions and the repository's detailed migration guide.

Reserved environment migrations

Recent releases reserve Garage config and credential environment names so the operator can prove mesh identity and drain safety. Existing objects with these overrides reconcile only through a fail-closed migration.

RPC secret override

  1. Keep the old GARAGE_RPC_SECRET override in place.
  2. Create a Secret with the exact same 64-hex value.
  3. Set spec.network.rpcSecretRef and annotate garage.rajsingh.info/migrate-legacy-rpc-secret=true in a staging-only update.
  4. Wait for the cluster status to confirm every managed Pod, Secret, and snapshot matches.
  5. Remove only the old RPC environment entry; leave the typed reference and migration annotation until the operator consumes it.

The operator never overwrites a mismatched existing Secret or guesses the value.

Config-file override

Remove GARAGE_CONFIG_FILE only after comparing the old effective TOML with the operator-rendered config, then add garage.rajsingh.info/acknowledge-legacy-config-migration=true until the coordinated rollout completes.

Broad envFrom, file-based credential overrides, and Admin/metrics credential overrides do not have an automatically provable startup value. Convert them before upgrading or use an explicit manual migration while workloads remain frozen.

Node-local pools

Node-local pools are introduced in the v0.7 line and require Kubernetes 1.27+, scheduling-gate support, enabled webhooks, and privileged workload namespaces. Existing LocalPath PVC GarageNodes are not automatically adoptable as node-local identities. Follow the migration section in the node-local guide.

Rollback

Rollback the chart only when the CRD and controller contracts are compatible with the stored resources. Do not roll back an on-disk Garage layout or a completed identity drain by restoring a container image. If a rollout is stuck, use garage.rajsingh.info/recover-storage-rollout with a new nonce after correcting the workload-only failure; do not delete the identity's PVCs.