Aegis Orchestrator
Guides

Upgrade Procedures

How to upgrade AEGIS platform components — image updates, database migrations, rolling upgrades, version compatibility, and rollback procedures.

Upgrade Procedures

This guide covers the process for upgrading AEGIS platform components to new versions.

Image Update Procedure

The standard upgrade path is to pull new images and redeploy pods.

Step 1: Update Image Tag

Edit .env to point to the new version:

# Pin to a specific version
AEGIS_IMAGE_TAG=1.3.0

Step 2: Pull New Images

# Authenticate if needed
make registry-login

# Pull updated images
podman pull ghcr.io/100monkeys-ai/aegis-runtime:1.3.0
podman pull ghcr.io/100monkeys-ai/aegis-temporal-worker:1.3.0
podman pull ghcr.io/100monkeys-ai/aegis-seal-gateway:1.3.0

Step 3: Redeploy

# Redeploy individual pods (preferred for minimal downtime)
make redeploy POD=core
make redeploy POD=temporal
make redeploy POD=seal-gateway

# Or full teardown and redeploy
make teardown
make deploy PROFILE=full

Step 4: Validate

make validate

Database Migrations

AEGIS runs database migrations automatically on startup. When upgrading to a version with schema changes:

  1. Back up the database first — see Backup & Restore
  2. Deploy the new version — migrations run during pod-core startup
  3. Verify — check runtime logs for successful migration messages
# Check migration status in logs
make logs POD=core | grep -i migrat

Always back up PostgreSQL before upgrading to a version with schema changes. While migrations are designed to be forward-compatible, having a backup allows rollback if issues arise.

Rolling Upgrade vs Full Teardown

Rolling Upgrade (Preferred)

Redeploy pods one at a time to minimize downtime:

# 1. Database first (if schema changes)
make redeploy POD=database

# 2. Core runtime
make redeploy POD=core

# 3. Temporal worker
make redeploy POD=temporal

# 4. Other pods as needed
make redeploy POD=seal-gateway
make redeploy POD=observability

Downtime: Brief per-pod restart (seconds to minutes).

Full Teardown

For major version upgrades or when pod definitions change:

make teardown
make deploy PROFILE=full
make bootstrap-secrets
make validate

Downtime: Full stack unavailable during teardown/deploy cycle.

Third-Party Component Upgrades

PostgreSQL

# 1. Backup
podman exec aegis-database-postgres pg_dumpall -U aegis > ./backups/pre-upgrade.sql

# 2. Update image tag in pod-database.yaml
# 3. Redeploy
make redeploy POD=database

# 4. Verify
podman exec aegis-database-postgres psql -U aegis -c "SELECT version();"

Temporal

make redeploy POD=temporal
# Temporal auto-setup handles schema migrations

Version Compatibility

AEGIS RuntimeTemporalPostgreSQLOpenBao
0.x (pre-alpha)1.22-1.2315+2.0+

During pre-alpha, there are no backward compatibility guarantees. Always test upgrades in a development environment first.

Rollback Procedure

If an upgrade causes issues:

# 1. Update .env to previous version
AEGIS_IMAGE_TAG=1.2.0

# 2. Redeploy affected pods
make redeploy POD=core

# 3. If database migrations are not backward-compatible, restore from backup
podman exec -i aegis-database-postgres psql -U aegis < ./backups/pre-upgrade.sql
make redeploy POD=core

# 4. Validate
make validate

See Also

Disaster Recovery

Recovery runbooks for AEGIS platform failure scenarios — pod failures, database corruption, secrets engine recovery, and full environment rebuild.

Troubleshooting

Diagnostic commands, common failure patterns, service dependency chains, and log analysis for AEGIS platform deployments.

On this page

Upgrade ProceduresImage Update ProcedureStep 1: Update Image TagStep 2: Pull New ImagesStep 3: RedeployStep 4: ValidateDatabase MigrationsRolling Upgrade vs Full TeardownRolling Upgrade (Preferred)Full TeardownThird-Party Component UpgradesPostgreSQLTemporalVersion CompatibilityRollback ProcedureSee Also