OperationsRunbooks
Version Upgrade Runbook
Step-by-step procedures for upgrading OGuardAI across Helm, Docker Compose, and systemd deployments
Upgrade OGuardAI from version N to N+1.
Pre-Upgrade Checklist
- Read the changelog. Note breaking changes.
- Back up current config:
helm get values guardai -o yaml > guardai-values-backup.yaml # Helm cp /etc/guardai/oguardai.yaml /etc/guardai/oguardai.yaml.bak # systemd - Confirm current deployment is healthy:
curl -sf http://guardai.internal:3000/v1/health - Session compatibility: sealed sessions from the same major version work with the same key.
- Policy compatibility: minor versions only add fields with defaults. Existing policies work as-is.
Helm Upgrade
helm diff upgrade guardai deploy/helm/oguardai --set server.image.tag=v0.2.0 -f guardai-values-backup.yaml
helm upgrade oguardai deploy/helm/oguardai --set server.image.tag=v0.2.0 -f guardai-values-backup.yaml --wait --timeout 5m
kubectl rollout status deployment/guardai --timeout=5mRollback:
helm history guardai
helm rollback guardai # previous revision
helm rollback guardai 3 # specific revisionDocker Compose Upgrade
cd deploy/docker
GUARDAI_VERSION=v0.2.0 docker compose pull
GUARDAI_VERSION=v0.2.0 docker compose up -d --no-deps server
GUARDAI_VERSION=v0.2.0 docker compose up -d --no-deps detector # if detector also upgraded
docker compose ps
curl -sf http://localhost:3000/v1/healthRollback:
GUARDAI_VERSION=v0.1.0 docker compose up -d --no-deps serversystemd Upgrade
curl -L -o /tmp/oguardai-server \
https://github.com/oronts/oguardai/releases/download/v0.2.0/oguardai-server-linux-amd64
chmod +x /tmp/oguardai-server
sudo systemctl stop oguardai-server
cp /usr/local/bin/oguardai-server /usr/local/bin/oguardai-server.bak
mv /tmp/oguardai-server /usr/local/bin/oguardai-server
sudo systemctl start oguardai-server
systemctl status oguardai-server
curl -sf http://localhost:3000/v1/healthRollback:
sudo systemctl stop oguardai-server
mv /usr/local/bin/oguardai-server.bak /usr/local/bin/oguardai-server
sudo systemctl start oguardai-serverPost-Upgrade Verification
Run these regardless of deployment method:
# Health
curl -sf http://guardai.internal:3000/v1/health | jq .
# Test transform
curl -s -X POST http://guardai.internal:3000/v1/transform \
-H "Content-Type: application/json" \
-d '{"input": "My email is test@example.com"}' | jq .
# Test rehydrate (use session_state from transform response)
curl -s -X POST http://guardai.internal:3000/v1/rehydrate \
-H "Content-Type: application/json" \
-d '{"output": "Your email is `{{email:xxxx}}`", "session_state": "<blob>"}' | jq .Monitor guardai_errors_total and guardai_transform_duration_seconds for 10 min after upgrade.
Compatibility Notes
- Sessions: Same key decrypts across minor versions. Do not rotate keys during upgrade.
- Policies: Additive changes only in minor versions. Existing files work without modification.
- API:
/v1/*endpoints are backward compatible within same major version. New response fields may appear; existing fields are never removed.