Skip to main content
Version: Next

Upgrade

Upgrading Lakehousecat is done by pulling a new Helm chart version and updating the Operator. The Operator then performs a rolling replacement of the managed pods.

How Upgrades Work​

The upgrade process follows these stages:

  1. You pull the new Helm chart version and run helm upgrade on the Operator
  2. The Operator reconciles the desired state against the running instance
  3. The Operator performs a rolling replacement of components — pods are replaced one at a time or in controlled groups
  4. Once all components reach the new version, the instance returns to healthy state

The Operator is designed to minimize downtime, but a brief interruption is possible when individual pods are replaced. Plan upgrades during a maintenance window, especially for production environments.

No Manual Service Upgrades​

Never upgrade individual services manually

Individual services managed by Lakehousecat (Airflow, Superset, ClickHouse, PostgreSQL, Valkey, SeaweedFS, and the Lakehousecat services themselves) must never be upgraded manually — for example, by running helm upgrade directly against a single service's chart. All upgrades must go through the Lakehousecat Operator.

Lakehousecat is tested and released as a specific combination of service versions. Only this provider-tested combination is the basis for a stable, supported deployment. Upgrading a single service independently — even to a newer version — breaks that tested combination and is not supported.

The Operator continuously enforces the correct version for every managed service. If a service's running image is changed outside of the Operator, the Operator detects the deviation on its next reconciliation cycle and automatically resets it back to the version released for your Lakehousecat version.

Example: Manually upgrading Airflow to a newer version, independent of a Lakehousecat Operator upgrade, is not supported. The Operator will revert it to the released version on the next reconciliation cycle.

To upgrade any service, always bump spec.version on the Lakehousecat (or LakehousecatPortal) Custom Resource and let the Operator perform the upgrade — see Upgrade Steps below.

Before You Upgrade​

Back up before upgrading

Always back up both secrets and Persistent Volume Claims (PVCs) before upgrading. If something goes wrong during the upgrade, a current backup is your recovery path.

See Backup and Restore for instructions.

Checklist:

  • Backup all secrets (including the encryption key)
  • Backup all PVCs (PostgreSQL, ClickHouse, SeaweedFS)
  • Schedule during a maintenance window
  • Notify users of the expected downtime window

Upgrade Steps​

Step 1 — Backup secrets and PVCs​

Run your standard backup procedure before proceeding.

Step 2 — Pull the new Helm chart version​

helm repo update lakehousecat

Step 3 — Upgrade the Operator​

helm upgrade lhc-operator lakehousecat/lakehousecat-operator \
  -n lhc-operator \
  -f operator-values.yaml \
  --version <new-version>

Replace <new-version> with the target Helm chart version. Pass the same values file as at install time: it carries the required targetNamespaces, without which the chart refuses to render.

Step 4 — Operator reconciles and replaces components​

The Operator detects that the running instance does not match the new desired state and begins replacing components. Monitor progress:

kubectl logs -f deployment/lhc-operator -n lhc-operator

Step 5 — Verify the instance is healthy​

kubectl get lakehousecats -A

A healthy instance shows Phase: Ready. If the phase does not return to Ready within a reasonable time, check the Operator logs and the instance pod status:

kubectl -n <instance-namespace> get pods
kubectl describe lakehousecat <instance-name> -n <instance-namespace>

Custom Resources and Manual Modifications​

The Operator manages only resources that are part of the defined Lakehousecat Custom Resource specification. It reconciles the cluster state toward the desired state on every cycle.

Do not manually modify pod images or manifests

Manual changes to pod images, resource manifests, or Kubernetes objects managed by the Operator are rolled back automatically on the next reconciliation cycle. The Operator maintains the defined state — manual overrides do not persist and may cause unexpected behavior during and after upgrades.

If you have made namespace-level modifications outside of the Lakehousecat CR spec, those modifications are not supported and may conflict with the Operator's reconciliation.

License and Token Renewal​

The Operator handles periodic license token renewal automatically. No manual action is required during normal operation.

If the Operator goes offline and the token expires:

The instance enters Administrator Mode — only the Administrator account can log in. Regular user sessions are blocked until the token is renewed.

If this occurs:

  1. Bring the Operator back online — it will renew the token on the next reconciliation cycle
  2. If the Operator cannot come back online or the token cannot be renewed, contact Lakehousecat support via portal.lakehousecat.com