Skip to main content
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

      Build docs developers (and LLMs) love

      Get started for freeTalk to us