Skip to main content

Upgrade Guide

How to upgrade STOA Platform between versions with zero downtime.

Upgrade Strategy​

STOA uses rolling updates by default. The upgrade order matters:

1. CRDs (if changed)
2. Database migrations (Alembic)
3. Control Plane API
4. STOA Gateway
5. Console UI + Portal

Pre-Upgrade Checklist​

  • Read the release notes for breaking changes
  • Back up PostgreSQL (see Backup & Recovery)
  • Export Keycloak realm
  • Note current versions: helm list -n stoa-system
  • Verify cluster health: kubectl get pods -n stoa-system

Upgrade Steps​

1. Update CRDs​

Helm does not upgrade CRDs automatically. Apply them manually:

kubectl apply -f charts/stoa-platform/crds/

2. Run Database Migrations​

If the release includes schema changes:

kubectl exec -n stoa-system deploy/control-plane-api -- \
  alembic upgrade head

3. Upgrade Helm Release​

helm repo update
helm upgrade stoa-platform stoa/stoa-platform \
  -n stoa-system \
  -f my-values.yaml \
  --version <NEW_VERSION>

Or from local chart:

helm upgrade stoa-platform ./charts/stoa-platform \
  -n stoa-system \
  -f my-values.yaml

4. Verify​

# Check pod status
kubectl get pods -n stoa-system

# Verify versions
kubectl get deploy -n stoa-system -o jsonpath='{range .items[*]}{.metadata.name}: {.spec.template.spec.containers[0].image}{"\n"}{end}'

# Health checks
curl -s https://api.<YOUR_DOMAIN>/health
curl -s https://mcp.<YOUR_DOMAIN>/health

Rolling Back​

Helm Rollback​

# List history
helm history stoa-platform -n stoa-system

# Rollback to previous revision
helm rollback stoa-platform <REVISION> -n stoa-system

Database Rollback​

If migrations need reverting:

kubectl exec -n stoa-system deploy/control-plane-api -- \
  alembic downgrade -1

Version Compatibility​

ComponentCompatibility Rule
Control Plane APIMust match database schema version
STOA GatewayCompatible with CP API N and N-1
Console UICompatible with CP API N and N-1
PortalCompatible with CP API N and N-1
CRDsMust be applied before chart upgrade
Keycloak24.x supported, test 25.x in staging

Zero-Downtime Upgrades​

STOA supports zero-downtime upgrades when:

  1. Multiple replicas are running (replicas >= 2)
  2. PodDisruptionBudget is configured:
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: stoa-gateway-pdb
  namespace: stoa-system
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: stoa-gateway
  1. Readiness probes are configured (default in Helm chart)
  2. Database migrations are backwards-compatible (additive only)