Manual Upgrade

Before upgrading, read the Migration Guide to check for any breaking changes.

To deploy a new release, first set the target version and update the paths to your values file and access key file:

export BOLTMCP_VERSION=0.5.9
export BOLTMCP_VALUES="$PWD/config/values-prod.yaml"
export HELM_REGISTRY_CONFIG="$PWD/keys/boltmcp-key.json"

Now run the upgrade:

helm upgrade boltmcp \
  oci://europe-west2-docker.pkg.dev/boltmcp-platform/boltmcp-alpha/charts/boltmcp \
  --version ${BOLTMCP_VERSION} \
  -n boltmcp \
  -f ${BOLTMCP_VALUES} \
  --wait \
  --timeout 15m

Verify the Upgrade

Confirm the new revision shows deployed:

helm history boltmcp -n boltmcp

Watch pods until all show Running / Completed:

kubectl get pods -n boltmcp -w

The boltmcp-keycloak-reconcile and boltmcp-migrate-core hook pods (both pre-upgrade) should show Completed. The reconcile pod's log lists every Keycloak resource it created, updated or left unchanged. If a pod is not starting, check its logs and events:

kubectl logs -n boltmcp <pod-name>
kubectl describe pod -n boltmcp <pod-name>

Check the Vault Seal Status

If the upgrade caused the Vault pod to restart, and auto-unseal isn't configured, it will come back sealed. Check the Sealed status with:

kubectl exec -n boltmcp deploy/boltmcp-vault -- vault status

If it reads true, unseal Vault again, or configure auto-unseal to avoid the manual step on future restarts.

Values-Only Changes

To apply a change to values-prod.yaml without a chart-version bump, re-run the same helm upgrade command above with the unchanged --version. Values render into the pod specs, so Helm rolls the affected deployments automatically — no manual restart is needed.

Editing the contents of the externally-managed application Secrets (boltmcp-database, boltmcp-oidc, boltmcp-auth) is different: that isn't a values change and Helm won't notice it. Pods read these Secrets only at startup, so restart the deployments that consume them:

kubectl rollout restart -n boltmcp deployment/<deployment>

The OIDC client secrets additionally have to be updated on the Keycloak side; see Rotating Secrets.

Recovering a stuck pending-upgrade release

If a helm upgrade is interrupted (timeout, Ctrl-C, OOM, kube-apiserver hiccup) the release record can be left in pending-upgrade state. Every subsequent helm upgrade will then fail with:

Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress

Before doing anything, make sure the state is actually stale: confirm no helm upgrade is still running in another terminal or CI job, and let any in-flight hook jobs from the interrupted attempt finish (retrying while a migration job is mid-run would delete and recreate it):

kubectl get jobs -n boltmcp

Where the upgrade stopped tells you what state the cluster is in. A timeout during the hook stage leaves the previous release's pods running, with the schema either fully migrated or untouched. A timeout during the rollout stage means a Deployment never became ready under --wait, so check kubectl get pods -n boltmcp and the failing pod's logs before clearing the record; the previous pods keep serving in the meantime.

To clear the stale record without losing the deployed resources, delete the stuck revision's Helm release Secret. Helm will fall back to the previous successful revision as the current state:

# Find the pending revision (column STATUS = pending-upgrade)
helm history boltmcp -n boltmcp

# Delete its release Secret
kubectl delete secret sh.helm.release.v1.boltmcp.v<N> -n boltmcp

# Confirm the release no longer shows pending-upgrade
helm history boltmcp -n boltmcp

# Re-run the upgrade as above
helm upgrade boltmcp ...

helm rollback is the textbook recovery, but it can fail with original object Secret with the name "boltmcp-auth" not found when rolling back across a chart version that changed which resources are Helm-managed. If that happens, fall back to the manual kubectl delete secret sh.helm.release.v1.boltmcp.v<N> approach above.