Upgrading

Palena's API is currently v1alpha1. Breaking changes may occur between minor versions until the API graduates to v1beta1. Production deployments should pin to a specific bundle or chart tag and test upgrades in staging first.

Compatibility rules during v1alpha1

When new CRD fields are introduced:

1. They will be optional with a sensible default.
2. Existing CRs will continue to reconcile unchanged.
3. Deprecations are announced at least one minor release before removal.

Any breaking change (field removal, enum tightening, required field addition) bumps the operator's minor version and is called out in the release notes.

Upgrading via OLM

# Edit the Subscription's channel
kubectl -n palena-system edit subscription palena-operator

# Or bump the CSV directly
operator-sdk run bundle-upgrade ghcr.io/palenaai/palena-operator-bundle:v0.0.2

OLM handles CRD updates and controller roll-over as part of the upgrade.

Upgrading via Helm

helm upgrade palena-operator deploy/charts/palena-operator \
  --namespace palena-system \
  --set image.tag=v0.0.2

CRD updates via Helm

Helm does not update CRDs on helm upgrade by default. If the new version adds fields, upgrade CRDs manually first:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/PalenaAI/palena-operator/v0.0.2/config/crd/bases/

Pre-upgrade checklist

Before upgrading in production:

• [ ] Read the release notes for breaking changes
• [ ] Back up existing CRs: kubectl get palenagateway,palenamodel,palenaui,palenaobservability,palenamcpserver -A -o yaml > palena-backup.yaml
• [ ] Upgrade in a staging environment first
• [ ] Verify upstream operators (CNPG, LiteLLM Operator, Langfuse Operator) meet the new version's minimum requirements
• [ ] Check kubectl get csv -n palena-system (OLM) or helm status palena-operator -n palena-system for the current version

Rolling back

If an upgrade introduces a regression:

# OLM
operator-sdk run bundle-upgrade ghcr.io/palenaai/palena-operator-bundle:v0.1.0

# Helm
helm rollback palena-operator --namespace palena-system

Rolling back is safe as long as no breaking CRD changes landed in the version you're rolling back from. If they did, you may need to convert CRs manually — the release notes will flag this.