Upgrade

Upgrade Infrahub to newer versions safely with minimal downtime

Upgrade your Infrahub deployment to benefit from new features, security fixes, and performance improvements. This page covers upgrade procedures, version compatibility, and rollback strategies.

Before you upgrade

Review release notes

Check the release notes for:

• Breaking changes
• Database migrations
• Configuration changes
• Deprecated features
• Known issues

Release notes: https://github.com/opsmill/infrahub/releases

Backup your deployment

Create a complete backup before upgrading:

# Using infrahub-backup tool
./infrahub-backup create

# Or backup manually
docker compose exec -T database neo4j-admin backup --to-path=/backups/ neo4j
docker compose exec -T task-manager-db pg_dump -Fc -U postgres -d prefect > prefect.dump

See the backup guide for complete procedures.

Check version compatibility

Supported upgrade paths:

• Patch versions (1.7.5 → 1.7.6): Direct upgrade
• Minor versions (1.6.x → 1.7.x): Direct upgrade
• Major versions (1.x → 2.x): May require migration steps

Unsupported:

• Skipping minor versions (1.5.x → 1.7.x): Upgrade sequentially
• Downgrading: Not supported, use backup restoration

Plan maintenance window

Typical upgrade times:

• Patch version: 5-10 minutes
• Minor version: 10-30 minutes
• Major version: 30-60 minutes (varies by deployment size)

During the upgrade:

• API will be unavailable
• Background tasks will be paused
• Active connections will be terminated

Docker Compose upgrade

Standard upgrade procedure

Step 1: Backup current deployment

./infrahub-backup create

Step 2: Download new Docker Compose file

Step 3: Update environment variables

Review changes in the new docker-compose.yml and update your .env file if needed:

# Compare environment variables
diff <(grep -E '^[A-Z_]+:' docker-compose.yml.backup | sort) \
     <(grep -E '^[A-Z_]+:' docker-compose.yml | sort)

Step 4: Pull new images

docker compose pull

Step 5: Stop services

docker compose stop

Step 6: Run database migrations

Migrations run automatically on first startup. If you want to run them manually:

docker compose run --rm infrahub-server infrahub db migrate

Step 7: Start services

docker compose up -d

Step 8: Verify upgrade

# Check version
curl http://localhost:8000/api/config | jq .version

# Check service health
docker compose ps

# View logs
docker compose logs -f infrahub-server

Rolling upgrade (minimal downtime)

For deployments with multiple API servers:

Step 1: Update one API server

# Scale down to 1 server
docker compose up -d --scale infrahub-server=1

# Pull new image
docker compose pull infrahub-server

# Update the running server
docker compose up -d infrahub-server

Step 2: Verify functionality

curl http://localhost:8000/api/health

Step 3: Scale up remaining servers

docker compose up -d --scale infrahub-server=3

Kubernetes upgrade

Helm chart upgrade

Step 1: Backup deployment

Follow Kubernetes backup procedures from the backup guide.

Step 2: Update Helm repository

helm repo update

Step 3: Review changes

# Check available versions
helm search repo infrahub --versions

# Compare values
helm get values infrahub -n infrahub > current-values.yml
helm show values oci://registry.opsmill.io/opsmill/chart/infrahub-enterprise \
  --version 4.1.0-medium > new-values.yml
diff current-values.yml new-values.yml

Step 4: Upgrade chart

Step 5: Monitor rollout

# Watch deployment progress
kubectl rollout status deployment/infrahub-server -n infrahub

# Check pod status
kubectl get pods -n infrahub -l app=infrahub

# View logs
kubectl logs -n infrahub -l service=infrahub-server -f

Step 6: Verify upgrade

# Check API version
kubectl exec -n infrahub deployment/infrahub-server -- \
  curl -s http://localhost:8000/api/config | jq .version

Version-specific migrations

Database schema migrations

Most releases include automatic database migrations. Monitor migration logs:

# Docker Compose
docker compose logs infrahub-server | grep migration

# Kubernetes
kubectl logs -n infrahub -l service=infrahub-server | grep migration

Configuration migrations

Some versions require configuration changes:

Example: Redis host configuration (chart 4.0.0+)

When upgrading to chart version 4.0.0 or later, add:

values.yml

infrahub:
  prefect-server:
    backgroundServices:
      messaging:
        redis:
          host: "infrahub-cache-master"

Data migrations

Occasionally, data format changes require migrations. These run automatically but may take time:

# Check migration status
curl http://localhost:8000/api/migrations/status

# View migration logs
docker compose logs infrahub-server | grep "data migration"

Troubleshooting upgrades

Migration failures

If migrations fail:

# View detailed logs
docker compose logs infrahub-server --tail 100

# Check database connectivity
docker compose exec database cypher-shell -u neo4j -c "SHOW DATABASES;"

# Manually run migrations
docker compose run --rm infrahub-server infrahub db migrate --verbose

Service startup failures

If services fail to start:

# Check health
docker compose ps

# View logs
docker compose logs --tail 50

# Check dependencies
docker compose exec database neo4j status
docker compose exec cache redis-cli ping

Incompatible configuration

If configuration is incompatible:

# Compare configurations
diff docker-compose.yml.backup docker-compose.yml

# Reset to defaults
cp docker-compose.yml.backup docker-compose.yml
docker compose up -d

Rollback procedures

Docker Compose rollback

Step 1: Stop services

docker compose stop

Step 2: Restore configuration

cp docker-compose.yml.backup docker-compose.yml

Step 3: Restore data

./infrahub-backup restore infrahub_backup_20250302_120000.tar.gz

Step 4: Restart services

docker compose up -d

Kubernetes rollback

Helm rollback:

# List releases
helm history infrahub -n infrahub

# Rollback to previous version
helm rollback infrahub -n infrahub

# Rollback to specific revision
helm rollback infrahub 5 -n infrahub

Manual rollback:

# Restore from backup
kubectl apply -f backup-manifests/

# Verify pods
kubectl get pods -n infrahub

Best practices

Pre-upgrade checklist

• Review release notes and breaking changes
• Create complete backup
• Test upgrade in non-production environment
• Schedule maintenance window
• Notify users of upcoming downtime
• Verify backup integrity
• Document current configuration

Post-upgrade validation

• Verify API version
• Check service health
• Test GraphQL queries
• Verify artifact generation
• Test Git repository sync
• Review logs for errors
• Monitor performance metrics

Upgrade testing

Always test upgrades in a non-production environment:

1. Deploy matching production version
2. Restore production backup
3. Perform upgrade procedure
4. Run integration tests
5. Document issues and workarounds
6. Update upgrade procedures

Related resources

• Backup and restore - Protect your data before upgrading
• Docker Compose deployment - Docker Compose configuration
• Kubernetes deployment - Kubernetes deployment
• Monitoring - Monitor upgrade health
• Release notes - Version-specific changes