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/livez - 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 oguardai deploy/helm/oguardai --set server.image.tag=v0.1.1 -f guardai-values-backup.yaml
helm upgrade oguardai deploy/helm/oguardai --set server.image.tag=v0.1.1 -f guardai-values-backup.yaml --wait --timeout 5m
kubectl rollout status deployment/oguardai --timeout=5mRollback:
helm history oguardai
helm rollback oguardai # previous revision
helm rollback oguardai 3 # specific revisionDocker Compose Upgrade
cd deploy/docker
# Build-based compose (default): rebuild from updated source
git pull origin main
docker compose build --no-cache server
docker compose up -d --no-deps server
docker compose up -d --no-deps detector # if detector also upgraded
docker compose ps
curl -sf http://localhost:3000/livezRollback:
# Checkout previous version and rebuild
git checkout v0.1.0
docker compose build --no-cache server
docker compose up -d --no-deps serversystemd Upgrade
The release-download URL below is illustrative. Published release artifacts are not yet available, so substitute your own build output or internal artifact URL until releases are published.
# Illustrative URL: replace with a published release asset or your own build
curl -L -o /tmp/oguardai-server \
https://github.com/oronts/oguardai/releases/download/v0.1.1/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/livezRollback:
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:
# Liveness (unauthenticated)
curl -sf http://guardai.internal:3000/livez
# Test transform (with auth)
curl -s -X POST http://guardai.internal:3000/v1/transform \
-H "Content-Type: application/json" \
-H "X-API-Key: $GUARDAI_API_KEY" \
-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" \
-H "X-API-Key: $GUARDAI_API_KEY" \
-d '{"output": "Your email is `{{email:xxxx:29ccba2d9234}}`", "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: From 1.0,
/v1/*endpoints follow the stability contract within a major version (new response fields may appear; existing fields are not removed). Pre-1.0 (0.x), the surface may still change.