Supabase on AWS with CDKTF

A production-ready deployment of Supabase on AWS using CDK for Terraform (CDKTF) in Python. This solution provides a highly automated, secure, and scalable infrastructure for running Supabase in your AWS environment.

✅ DevOps Take-Home Requirements Status

This deployment successfully implements all required components for the DevOps take-home project:

Required Infrastructure Components - ✅ COMPLETED

✅ Network: Secure and isolated VPC with public/private subnets, NAT Gateways, and proper routing
✅ Kubernetes: Amazon EKS deployed in private subnets, spanning 2+ availability zones for high availability
✅ Managed Database: Aurora PostgreSQL in private subnets with high availability and automated backups
✅ Object Storage: S3 bucket with encryption, versioning, and proper IAM access policies
✅ Secrets Management: AWS Secrets Manager storing all sensitive configurations (JWT secrets, DB credentials, API keys)

Security in IaC - ✅ COMPLETED

✅ Network Access Controls: Security groups with least privilege (EKS control plane, nodes, RDS isolation)
✅ IAM Least Privilege: Service-specific IRSA roles with minimal required permissions
✅ Kubernetes NetworkPolicies: Pod-to-pod communication restrictions implemented

Production-Ready Features - ✅ COMPLETED

✅ External Secrets Operator: Secure injection of AWS Secrets Manager secrets into Kubernetes using IRSA authentication
✅ Horizontal Pod Autoscaler: Auto-scaling for Auth, REST, Storage, and Kong components with CPU/memory thresholds
✅ AWS Load Balancer Controller: ALB ingress with SSL termination and health checks
✅ Cluster Autoscaler: Automatic EKS node scaling based on pod demands with Graviton2 instances
✅ Multi-AZ Deployment: Infrastructure distributed across multiple availability zones for high availability
✅ Metrics Server: Kubernetes metrics collection for HPA functionality
✅ Persistent Storage: GP3 EBS volumes with encryption and backup strategies

Status: All requirements successfully implemented and deployed! 🎉

✨ Recent Updates

🔒 External Secrets Integration: Fully working AWS Secrets Manager integration with proper IRSA authentication
📈 Horizontal Pod Autoscaler: All critical services now auto-scale based on CPU and memory usage
📊 Metrics Server: Successfully deployed and providing real-time resource metrics
🔧 CDKTF Architecture: Complete infrastructure as code implementation with modular components

🏗️ Architecture Overview

This deployment creates a comprehensive AWS infrastructure optimized for Supabase:

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AWS Cloud                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                      VPC                                │    │
│  │                                                         │    │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │    │
│  │  │   Public     │  │   Public     │  │   Private    │  │    │
│  │  │   Subnet     │  │   Subnet     │  │   Subnet     │  │    │
│  │  │   (AZ-a)     │  │   (AZ-b)     │  │   (AZ-a)     │  │    │
│  │  │              │  │              │  │              │  │    │
│  │  │ ┌──────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │  │    │
│  │  │ │   NAT    │ │  │ │   NAT    │ │  │ │   EKS    │ │  │    │
│  │  │ │ Gateway  │ │  │ │ Gateway  │ │  │ │  Nodes   │ │  │    │
│  │  │ └──────────┘ │  │ └──────────┘ │  │ └──────────┘ │  │    │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │    │
│  │                                                         │    │
│  │  ┌──────────────┐  ┌──────────────┐                    │    │
│  │  │   Private    │  │   Database   │                    │    │
│  │  │   Subnet     │  │   Subnet     │                    │    │
│  │  │   (AZ-b)     │  │   (AZ-a)     │                    │    │
│  │  │              │  │              │                    │    │
│  │  │ ┌──────────┐ │  │ ┌──────────┐ │                    │    │
│  │  │ │   EKS    │ │  │ │   RDS    │ │                    │    │
│  │  │ │  Nodes   │ │  │ │PostgreSQL│ │                    │    │
│  │  │ └──────────┘ │  │ └──────────┘ │                    │    │
│  │  └──────────────┘  └──────────────┘                    │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                 External Services                       │    │
│  │                                                         │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │    │
│  │  │     S3      │  │   Secrets   │  │  Route 53   │      │    │
│  │  │   Storage   │  │   Manager   │  │   (DNS)     │      │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Supabase Components in EKS

┌─────────────────────────────────────────────────────────────────┐
│                      EKS Cluster                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Ingress Layer                         │    │
│  │                                                         │    │
│  │  ┌─────────────┐              ┌─────────────┐            │    │
│  │  │   AWS ALB   │──────────────│   Kong      │            │    │
│  │  │ Controller  │              │  Gateway    │            │    │
│  │  └─────────────┘              └─────────────┘            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                 Application Layer                       │    │
│  │                                                         │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │    │
│  │  │   Studio    │  │     Auth    │  │    REST     │      │    │
│  │  │ (Dashboard) │  │  (GoTrue)   │  │ (PostgREST) │      │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │    │
│  │                                                         │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │    │
│  │  │   Storage   │  │  Realtime   │  │    Meta     │      │    │
│  │  │     API     │  │   Server    │  │     API     │      │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Infrastructure Layer                       │    │
│  │                                                         │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │    │
│  │  │  External   │  │   Cluster   │  │    HPA      │      │    │
│  │  │  Secrets    │  │ Autoscaler  │  │ Metrics     │      │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

🚀 Key Features

Infrastructure as Code

CDKTF (Python): Modern IaC using familiar programming constructs
Modular Architecture: Clean separation of concerns with reusable components
Type Safety: Python type hints and validation throughout

High Availability & Scalability

Multi-AZ Deployment: Resources distributed across 2 availability zones
Auto Scaling: HPA for pods, Cluster Autoscaler for nodes
Load Balancing: AWS Application Load Balancer with health checks
Database HA: Aurora PostgreSQL with read replicas

Security Best Practices

Network Isolation: Private subnets for all compute resources
Secrets Management: AWS Secrets Manager with External Secrets Operator
IAM Least Privilege: Service-specific roles with minimal permissions
Encryption: At-rest and in-transit encryption throughout

Observability & Monitoring

CloudWatch Integration: Native AWS monitoring and logging
Performance Insights: Database performance monitoring
Application Metrics: Built-in metrics for all Supabase components

📋 Prerequisites

Required Tools

AWS CLI v2 - configured with appropriate credentials
kubectl - Kubernetes command-line tool
Helm 3 - Kubernetes package manager
CDKTF CLI - CDK for Terraform
Python 3.8+ - with pip

AWS Requirements

AWS account with appropriate permissions
Service quotas sufficient for EKS, RDS, and other services
Domain name for SSL certificate (optional but recommended)

Minimum IAM Permissions

Your AWS credentials need permissions for:

VPC and networking resources
EKS cluster and node group management
RDS cluster creation and management
S3 bucket operations
Secrets Manager operations
IAM role and policy management
CloudWatch and CloudFormation

🛠️ Technology Choices Justification

Why CDKTF over Terraform?

Familiarity: Python provides better developer experience than HCL
Type Safety: Compile-time validation prevents common errors
Modularity: Object-oriented design enables better code organization
Testing: Unit testing infrastructure code with familiar tools

Why EKS over ECS/Fargate?

Kubernetes Native: Supabase community charts are designed for K8s
Flexibility: Better control over resource allocation and scaling
Ecosystem: Rich ecosystem of operators and tools
Portability: Can be migrated to other K8s platforms if needed

Why Aurora PostgreSQL over RDS PostgreSQL?

High Availability: Built-in multi-AZ replication
Performance: Better performance at scale
Backup & Recovery: Continuous backup with point-in-time recovery
Compatibility: Full PostgreSQL compatibility

📖 Quick Start

1. Clone and Setup

git clone <repository-url>
cd supabase-aws-cdktf

2. Configure AWS CLI

aws configure
# Enter your AWS credentials, region (us-west-2), and output format (json)

3. Deploy Infrastructure and Supabase

./scripts/deploy.sh

This will:

Install Python dependencies
Deploy AWS infrastructure (15-20 minutes)
Configure kubectl for EKS
Install essential Kubernetes components
Configure External Secrets Operator
Deploy Supabase with Helm

4. Verify Deployment

./scripts/verify.sh

📚 Detailed Deployment Instructions

Step 1: Infrastructure Provisioning

The CDKTF deployment creates the following AWS resources:

Networking
- VPC with public/private subnets across 2 AZs
- Internet Gateway and NAT Gateways for internet access
- Route tables and security groups
Compute
- EKS cluster with managed node groups
- Auto Scaling Groups with Graviton2 instances
Database
- Aurora PostgreSQL cluster with primary and replica instances
- Encrypted storage with automated backups
Storage
- S3 bucket with versioning and encryption
- Lifecycle policies for cost optimization
Security
- Secrets Manager for sensitive configuration
- IAM roles with least-privilege access
- Security groups with minimal required access

# Deploy infrastructure only
cdktf deploy supabase-aws --auto-approve

Step 2: Kubernetes Configuration

After infrastructure deployment:

# Configure kubectl
aws eks update-kubeconfig --region us-west-2 --name supabase-eks

# Verify cluster access
kubectl cluster-info

Step 3: Install Essential Components

# Create namespace
kubectl create namespace supabase

# Install External Secrets Operator
helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets \
  --namespace external-secrets-system \
  --create-namespace \
  --set installCRDs=true

# Install AWS Load Balancer Controller
kubectl apply -f k8s/aws-load-balancer-controller.yaml

# Install Cluster Autoscaler
kubectl apply -f k8s/cluster-autoscaler.yaml

Step 4: Configure Secrets Integration

The External Secrets Operator is automatically configured via CDKTF to pull secrets from AWS Secrets Manager:

# Verify External Secrets are working
kubectl get clustersecretstore aws-secrets-manager-cluster
kubectl get externalsecrets -n supabase
kubectl get secrets -n supabase

# Check specific secrets
kubectl get secret supabase-database-secret -n supabase -o yaml
kubectl get secret supabase-jwt-secret -n supabase -o yaml
kubectl get secret supabase-api-keys-secret -n supabase -o yaml

The deployment automatically creates and syncs the following secrets from AWS Secrets Manager:

supabase-database-secret - Database connection details
supabase-jwt-secret - JWT authentication secret
supabase-api-keys-secret - API keys (anon, service role)
supabase-storage-secret - S3 storage configuration
supabase-auth-secret - Auth service configuration

Step 5: Deploy Supabase

# Add Supabase Helm repository
helm repo add supabase https://supabase-community.github.io/supabase-kubernetes

# Deploy Supabase
helm install supabase supabase/supabase \
  --namespace supabase \
  --values k8s/values.yaml \
  --timeout 15m

🔍 Verification Procedures

1. Infrastructure Health Check

# Check AWS resources
aws eks describe-cluster --name supabase-eks --query 'cluster.status'
aws rds describe-db-clusters --db-cluster-identifier supabase-postgres --query 'DBClusters[0].Status'

# Check Kubernetes cluster
kubectl get nodes
kubectl get pods -n supabase

2. Application Health Check

# Get Load Balancer URL
kubectl get ingress -n supabase

# Check HPA status
kubectl get hpa -n supabase

# Check External Secrets status
kubectl get externalsecrets -n supabase
kubectl get clustersecretstore aws-secrets-manager-cluster

# Test endpoints
curl -k https://<load-balancer-url>/health
curl -k https://<load-balancer-url>/rest/v1/

3. Complete Verification

# Run comprehensive verification
./scripts/verify.sh

This script performs:

Infrastructure validation
Kubernetes cluster health check
Metrics Server and HPA verification
External secrets synchronization verification
Supabase component status check
Load balancer and ingress validation
Auto-scaling functionality tests
Smoke tests on API endpoints

Expected Endpoints

After successful deployment:

Supabase Studio: https://<load-balancer-url>/studio
REST API: https://<load-balancer-url>/rest/v1/
Realtime: wss://<load-balancer-url>/realtime/v1/websocket
Storage API: https://<load-balancer-url>/storage/v1/
Auth API: https://<load-balancer-url>/auth/v1/

🔧 Configuration Customization

Environment Variables

Key configuration can be customized via environment variables:

export AWS_REGION="us-east-1"  # Default: us-west-2
export CLUSTER_NAME="my-supabase"  # Default: supabase-eks

Scaling Configuration

Adjust scaling parameters in k8s/values.yaml:

# Horizontal Pod Autoscaler settings
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

Instance Types and Sizing

Modify instance types in infrastructure/eks.py:

# EKS Node Group configuration
instance_types=["t3.medium"]  # Change to desired instance type
scaling_config={
    "desired_size": 3,
    "max_size": 10,
    "min_size": 2
}

Database Configuration

Adjust database settings in infrastructure/rds.py:

# Aurora PostgreSQL configuration
instance_class="db.r6g.large"  # Graviton2 instances
backup_retention_period=7       # Backup retention days

🔐 Security & Scalability Deep Dive

Network Security

Network Isolation
- All compute resources in private subnets
- Database in dedicated subnets with no internet access
- NAT Gateways provide controlled internet access
Security Groups
- Minimal port exposure (only necessary ports)
- Source-based access control
- Application layer filtering
Encryption
- RDS encryption at rest with AWS KMS
- S3 bucket encryption with AES-256
- Secrets Manager automatic encryption

Secrets Management

AWS Secrets Manager
- Centralized secret storage
- Automatic rotation capabilities
- Fine-grained access control
External Secrets Operator
- Kubernetes-native secret synchronization
- IRSA (IAM Roles for Service Accounts) authentication
- Automatic secret refresh
Least Privilege Access
- Service-specific IAM roles
- Minimal required permissions
- Regular access review and rotation

Scalability Considerations

Horizontal Scaling
- HPA scales pods based on CPU/memory usage
- Cluster Autoscaler adds nodes as needed
- Load balancer distributes traffic evenly
Database Scaling
- Aurora read replicas for read scaling
- Vertical scaling through instance class changes
- Connection pooling for efficient connection use
Storage Scaling
- S3 provides virtually unlimited storage
- Aurora storage auto-scales up to 128TB
- EBS volumes can be expanded as needed

🚨 Troubleshooting

Common Issues

1. Cluster Connection Issues

# Re-configure kubectl
aws eks update-kubeconfig --region us-west-2 --name supabase-eks

# Check IAM permissions
aws sts get-caller-identity

2. Pod Startup Issues

# Check pod logs
kubectl logs -n supabase <pod-name>

# Check resource availability
kubectl describe pod -n supabase <pod-name>

3. External Secrets Not Syncing

# Check External Secrets Operator logs
kubectl logs -n external-secrets-system deployment/external-secrets

# Check ClusterSecretStore status
kubectl describe clustersecretstore aws-secrets-manager-cluster

# Check IRSA configuration
kubectl describe serviceaccount external-secrets-sa -n supabase

# Verify IAM trust policy (common issue: OIDC URL format)
aws iam get-role --role-name supabase-external-secrets-role --query 'Role.AssumeRolePolicyDocument'

# Test service account token manually
kubectl run test-aws --image=amazon/aws-cli --rm -it --restart=Never \
  --serviceaccount=external-secrets-sa -n supabase -- aws sts get-caller-identity

4. Load Balancer Not Accessible

# Check ALB status in AWS Console
aws elbv2 describe-load-balancers

# Check ingress configuration
kubectl describe ingress -n supabase

Debugging Commands

# Get all resources in namespace
kubectl get all -n supabase

# Check events for errors
kubectl get events -n supabase --sort-by=.metadata.creationTimestamp

# Check resource usage and HPA
kubectl top pods -n supabase
kubectl top nodes
kubectl get hpa -n supabase

# Check External Secrets status
kubectl get clustersecretstore aws-secrets-manager-cluster
kubectl get externalsecrets -n supabase
kubectl describe externalsecret <secret-name> -n supabase

# Check metrics server
kubectl get deployment metrics-server -n kube-system

Log Locations

EKS Cluster Logs: CloudWatch Logs /aws/eks/supabase-eks/cluster
Application Logs: kubectl logs -n supabase <pod-name>
External Secrets Logs: kubectl logs -n external-secrets-system deployment/external-secrets
Metrics Server Logs: kubectl logs -n kube-system deployment/metrics-server
Cluster Autoscaler Logs: kubectl logs -n kube-system deployment/cluster-autoscaler
AWS Load Balancer Controller: kubectl logs -n kube-system deployment/aws-load-balancer-controller

🧹 Tear-Down Instructions

Complete Cleanup

To completely remove all resources and avoid ongoing charges:

./scripts/teardown.sh

This script will:

Remove Supabase Helm release
Clean up Kubernetes resources
Delete Load Balancers and Target Groups
Empty S3 buckets
Remove security groups
Destroy all CDKTF-managed infrastructure

Manual Cleanup

If the automated script fails, manually clean up in this order:

Kubernetes Resources

helm uninstall supabase -n supabase
kubectl delete namespace supabase external-secrets-system

Load Balancers

# Delete ALBs from AWS Console or CLI
aws elbv2 describe-load-balancers
aws elbv2 delete-load-balancer --load-balancer-arn <arn>

Infrastructure
```
cdktf destroy supabase-aws
```

Cost Monitoring

After teardown, verify no charges:

Check AWS Cost Explorer
Verify no running EC2 instances
Confirm S3 buckets are empty
Check for any remaining Load Balancers

💡 Future Improvements

Short Term

SSL/TLS Certificate: Integrate ACM certificates for HTTPS termination
Custom Domain: Route53 integration for custom domains
Monitoring Dashboards: CloudWatch dashboards for HPA and External Secrets metrics
Backup Automation: Automated backup verification and restore testing

Medium Term

Multi-Region: Cross-region replication and failover capabilities
CI/CD Integration: GitOps workflow with ArgoCD for automated deployments
Cost Optimization: Spot instances, reserved capacity, and auto-scaling policies
Security Hardening: WAF integration, DDoS protection, and security scanning

Long Term

Service Mesh: Istio integration for advanced traffic management and security
Advanced Observability: Prometheus, Grafana, and distributed tracing with Jaeger
Disaster Recovery: Automated failover and recovery procedures with RTO/RPO targets
Compliance: SOC2, HIPAA, PCI-DSS and other compliance frameworks

Current Status (Completed)

✅ HPA Implementation: All critical services auto-scale based on CPU/memory
✅ External Secrets: Full AWS Secrets Manager integration with IRSA
✅ Metrics Server: Resource metrics collection for scaling decisions
✅ Multi-AZ Resilience: Infrastructure distributed across availability zones

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For issues and questions:

Check the troubleshooting section above
Search existing GitHub issues
Create a new issue with detailed information
Include logs and configuration for faster resolution

🙏 Acknowledgments

Supabase for the amazing open-source platform
Supabase Community for Kubernetes charts
CDKTF Team for the excellent IaC framework
AWS for providing robust cloud infrastructure

Happy Building! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
infrastructure		infrastructure
k8s		k8s
scripts		scripts
supabase-kubernetes		supabase-kubernetes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
cdktf.json		cdktf.json
main.py		main.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation