Manual Upgrade

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.3.8
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} \
  --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-migrate-core and boltmcp-seed pods created by the post-upgrade hooks should show Completed. 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>

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

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
helm upgrade boltmcp ... -f ./config/values-prod.yaml

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.