Upgrade FeatBit Deployment

Guides safe, three-step upgrades of FeatBit deployments: check database migrations, test locally, deploy to production.

Quick Start

# 1. Check migrations
ls migration/ && cat migration/RELEASE-v<version>.md

# 2. Test locally
kubectl config use-context docker-desktop
helm upgrade featbit-test charts/featbit \
  -f charts/featbit/examples/standard/featbit-standard-local-pg.yaml

# 3. Deploy to AKS
az aks get-credentials --resource-group <rg> --name <cluster>
helm upgrade <release> featbit/featbit \
  -f charts/featbit/examples/aks/featbit-aks-values.local.yaml \
  --namespace <ns>

Three-Step Upgrade Workflow

Step 1: Check Database Migrations

⚠️ CRITICAL: FeatBit does NOT auto-execute migrations.

# List migration files
ls migration/

# Read migration for target version
cat migration/RELEASE-v<target-version>.md

Actions required:

• • Review database schema changes
• • Backup database
• • Execute migrations manually (DBA)
• • Verify schema changes applied

📄 Complete Guide: references/database-migrations.md

Step 2: Test Locally on Docker Desktop

Test upgrades locally before production:

# Switch to Docker Desktop K8s
kubectl config use-context docker-desktop

# Dry-run upgrade
helm upgrade featbit-test charts/featbit \
  -f charts/featbit/examples/standard/featbit-standard-local-pg.yaml \
  --dry-run

# Apply if dry-run succeeds
helm upgrade featbit-test charts/featbit \
  -f charts/featbit/examples/standard/featbit-standard-local-pg.yaml

# Monitor rollout
kubectl get pods -w

Verification:

kubectl get pods                               # All Running
kubectl logs -l app.kubernetes.io/name=featbit-api --tail=50
kubectl port-forward service/featbit-ui 8081:8081
curl http://localhost:5000/health              # API health check

📄 Complete Guide: references/local-testing-guide.md

Step 3: Deploy to Production (AKS)

After successful local testing:

# Azure login and AKS access
az login
az aks get-credentials --resource-group <rg> --name <cluster>
kubectl config use-context <aks-context>

# Verify current release
helm list -A | grep featbit

# Update Helm repo
helm repo update featbit

# Dry-run with AKS values
helm upgrade <release-name> featbit/featbit \
  -f charts/featbit/examples/aks/featbit-aks-values.local.yaml \
  --namespace <namespace> \
  --dry-run

# Apply if dry-run succeeds
helm upgrade <release-name> featbit/featbit \
  -f charts/featbit/examples/aks/featbit-aks-values.local.yaml \
  --namespace <namespace>

# Monitor deployment
kubectl get pods -n <namespace> -w

Post-upgrade verification:

kubectl rollout status deployment/featbit-api -n <ns>
curl https://api.yourdomain.com/health
curl https://els.yourdomain.com/health

📄 Complete Guide: references/aks-deployment-guide.md

Critical Concepts

Database Migrations:

• •NOT automated by Helm chart
• •Located in migration/RELEASE-v{version}.md
• •Must be executed manually before upgrade
• •Always backup database first

Chart Sources:

• •Local testing: charts/featbit (local path)
• •AKS/Production: featbit/featbit (published from Helm repo)
• •Never mix local and published charts

External URLs (Production):

apiExternalUrl: "https://api.featbit.com"
evaluationServerExternalUrl: "https://els.featbit.com"

⚠️ Without these, client SDKs cannot connect.

Pre-Upgrade Checklist

Database:

• • Migration scripts reviewed and executed
• • Database backup completed and verified
• • Connection strings validated

Kubernetes:

• • kubectl access to target cluster
• • Helm >= 3.7.0, kubectl >= 1.23 installed
• • Sufficient cluster resources

Configuration:

• • External URLs configured (production)
• • Managed services validated (PostgreSQL/Redis)
• • Secrets and ConfigMaps updated
• • TLS certificates valid

Operational:

• • Current Helm revision noted (rollback plan)
• • Team notified
• • Monitoring ready

Troubleshooting

Quick Rollback

helm history <release> -n <namespace>
helm rollback <release> <revision> -n <namespace>

Debug Commands

kubectl get pods -n <namespace>
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

📄 Complete Guide: references/troubleshooting.md

Common Issues

See references/troubleshooting.md for detailed solutions.

Best Practices

1. •✅ Always test locally first - Catch issues early
2. •✅ Use dry-run extensively - Simulate before applying
3. •✅ Review migrations - Understand database changes
4. •✅ Backup before upgrade - Database and configurations
5. •✅ Monitor during upgrade - Watch logs and status
6. •✅ Have rollback plan - Note current revision
7. •✅ Staged rollout - Dev → Staging → Production
8. •✅ External URLs - Required for production
9. •✅ Managed services - Use external providers for production
10. •✅ Document changes - Track customizations

Reference Guides

• •references/database-migrations.md - Migration workflow, backup, rollback
• •references/local-testing-guide.md - Docker Desktop K8s testing
• •references/aks-deployment-guide.md - AKS deployment, Azure CLI
• •references/troubleshooting.md - Common issues and solutions

Tools Required

• •Helm >= 3.7.0
• •kubectl >= 1.23
• •Azure CLI (for AKS)
• •Docker Desktop with Kubernetes (for local testing)

Support

• •Repository: https://github.com/featbit/featbit-charts
• •Documentation: https://docs.featbit.co/
• •Issues: https://github.com/featbit/featbit-charts/issues