Skip to main content
Version: 0.0.41

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.

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 \
  --version <new-version>

Replace <new-version> with the target Helm chart version.

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