Looking for Kubernetes? This guide covers ECS (Elastic Container Service) deployment. For Kubernetes/EKS deployment, see the EKS + Terraform guide.
Overview
Deploy Runlayer on AWS ECS (Elastic Container Service) with Fargate using Terraform. This provides a serverless container deployment without managing Kubernetes clusters. Choose between minimal configuration (5 required parameters) or enterprise configuration (full customization). Infrastructure Repository: anysource-AI/runlayer-infraThis deployment creates AWS resources that incur costs. Typical costs range
from $100-400/month depending on configuration.
Quick Start
Step 1: Get the infrastructure code Choose one of these options:- Minimal (Recommended)
- Enterprise
Get production-ready infrastructure with these parameters:That’s it! You get production-ready defaults for everything else.
Configuration Options
Minimal Configuration
Required:- Database: Aurora PostgreSQL 16.6, 2-16 ACUs, private subnets, 7-day backups
- Security: Public ALB with internet access, private database/cache
- SSL: Automatic ACM certificate creation (requires domain ownership; enable
enable_acm_dns_validationto have Terraform manage Route53 validation records and the ALIAS record pointing to the ALB) - Scaling: 2 backend + 2 frontend containers, auto-scale to 10 max
- Resources: Backend 512 CPU/1024 MB, Frontend 512 CPU/1024 MB
- Resources: Backend 2048 CPU/4096 MB, Frontend 512 CPU/1024 MB
- Network: 3-AZ VPC with /16 CIDR, public/private subnets
- Monitoring: CloudWatch logs for all services
Enterprise Configuration
All minimal options plus 160+ customizable parameters:Database Configuration
Database Configuration
Security Configuration
Security Configuration
Dual ALB Setup (Split-Horizon DNS)
Dual ALB Setup (Split-Horizon DNS)
- Public access required (e.g., ChatGPT, external integrations)
- Private network access for internal services (stays within VPC/peering)
- Single domain name (
runlayer.example.com) resolves differently based on network context
- Public DNS → Public ALB (internet traffic)
- Private DNS → Internal ALB (VPC/peered traffic)
- ECS services register with both ALBs
- WAF applies only to public ALB
VPC Peering for Cross-VPC Connectivity
VPC Peering for Cross-VPC Connectivity
Enable VPC peering to allow traffic between the Runlayer VPC and other VPCs (for example, a customer’s existing VPC or internal services VPC).Security Features:
- ✅ Required peer validation - All connections must specify
peer_owner_id - ✅ Automatic acceptance after validation - Validation is the security control
- ✅ Automatic routing - Routes configured only for validated connections
- ✅ Security group integration - Backend allows traffic from validated peer CIDRs
- The peer VPC must initiate the peering connection first
- You need the peering connection ID (
pcx-xxxxx) - You need the peer VPC’s CIDR block
- You MUST provide the peer AWS account ID for security validation
- Connecting to a customer’s existing VPC for internal API access
- Multi-VPC architectures with centralized services
- Hybrid cloud setups with on-premises connectivity
VPC peering only works when the module creates the VPC (not with
existing_vpc_id).Service Scaling
Service Scaling
Network Configuration
Network Configuration
Monitoring & Alerting
Monitoring & Alerting
- ECS Services: CPU utilization (80%), Memory utilization (85%)
- RDS Database: CPU utilization (80%), Connection count (50), Freeable Memory, Disk Queue Depth, Read/Write IOPS, Free Storage Space
- Redis Cache: CPU utilization (80%), Memory utilization (85%)
- Load Balancer: Response time (5s), Unhealthy targets, 5XX error count
- VPC: Flow logs for network traffic analysis and security monitoring
- Configurable alarm thresholds for all RDS metrics
- 365-day log retention for ECS services and prestart containers
- VPC Flow Logs with customizable traffic type monitoring
- ALB 5XX error tracking with configurable thresholds
Optional Services
Optional Services
Prerequisites
1
Install Tools
2
AWS Requirements
- AWS account with sufficient permissions
- Domain name you control (required for SSL certificate creation)
- Adequate service quotas (VPC, RDS, ECS)
The domain name is required because Runlayer creates an SSL certificate automatically. You must be able to validate domain ownership through DNS.
3
SSL Certificate (Enterprise Only)
Deployment
1. Get Infrastructure Code
2. Configure
3. Deploy
Deployment takes 15-20 minutes. SSL certificate validation may add 5-10
minutes.
4. Automated Database Setup
Database initialization is completely automated: What happens automatically:- Database Connection: Prestart container waits for Aurora PostgreSQL to be ready
- Schema Migration: Runs
alembic upgrade headto apply latest database schema - Logging: All setup activity logged to CloudWatch under
prestart-logs-[environment] - Error Handling: Backend won’t start if database setup fails
- Database password and secret keys are created securely
5. Update Application Secrets (Optional)
6. Verify Deployment
Architecture
Cost Estimation
| Component | Minimal | Enterprise |
|---|---|---|
| ECS Services | $50-80 | $150-300 |
| Aurora Database | $30-60 | $100-400 |
| ElastiCache | $15-30 | $50-150 |
| Load Balancer | $20-25 | $20-25 |
| Monitoring | $5-10 | $10-25 |
| Other (NAT, Storage) | $10-20 | $30-50 |
| Monthly Total | $130-225 | $360-950 |
Costs vary by region and usage. Use AWS Pricing
Calculator for precise estimates.
Common Use Cases
Private Enterprise Deployment
High Availability Production
Development Environment
Production with Monitoring
Troubleshooting
SSL Certificate Validation Fails
SSL Certificate Validation Fails
Solution: Ensure DNS validation records are created in Route53:
Application Not Accessible
Application Not Accessible
Solution: Check security groups and target health:
High Costs
High Costs
Solution: Optimize resource sizing:
- Use
environment = "development"for testing - Reduce database
min_capacityandmax_capacity - Lower service
desired_countand CPU/memory - Set shorter
backup_retentionperiods
Monitoring Alerts Not Working
Monitoring Alerts Not Working
Solution: Check CloudWatch alarm configuration:Common issues:
- CloudWatch alarm thresholds too high
- Alarm actions disabled
- Missing CloudWatch permissions
ECS vs EKS: Which to Choose?
| Factor | ECS (This Guide) | EKS |
|---|---|---|
| Complexity | Lower - Simpler to manage | Higher - Kubernetes expertise needed |
| Cost | $130-225/month | $200-800/month |
| Scaling | Auto-scaling with Fargate | More granular control |
| Ecosystem | AWS-specific | Kubernetes ecosystem |
| Best For | Simpler deployments, AWS-native | Complex workloads, multi-cloud |
Next Steps
Configuration
Configure application settings and integrations
EKS + Terraform
Deploy on Kubernetes using EKS with Terraform for more advanced scenarios
Helm + Kubernetes
Deploy application using Helm charts (after provisioning EKS infrastructure)