ECS + Terraform

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. The stack runs entirely in your AWS account: VPC, ALB, Aurora, Redis, Secrets Manager, and ECS services. How Runlayer is delivered:

Artifact	Delivery	Notes
Terraform module	Private S3 (`runlayer-infrastructure-modules`)	Versioned `.tar.gz` archives; pin a module version in `source`
Container images	Private ECR (CustomerDistribution `088332244652`)	Tagged by `app_version` (or override with `ecr_repositories`)

Runlayer grants your AWS account read access to the S3 module catalog and pull access to the ECR repositories during onboarding. Contact support@runlayer.com if terraform init or image pulls return AccessDenied.

This deployment creates AWS resources that incur costs. Typical costs range from $100-400/month depending on configuration.

Prerequisites

Install Tools

# AWS CLI
brew install awscli
aws configure

# Terraform >= 1.9
brew install terraform
terraform version

AWS Requirements

AWS account with permission to create VPC, ECS, RDS, ElastiCache, ALB, IAM, Secrets Manager, S3, CloudWatch, and Lambda resources
Domain name you control (for DNS records and SSL)
Adequate service quotas (VPC, RDS, ECS; GPU quota if enabling ToolGuard)
Outbound internet from private subnets (NAT or VPC endpoints) so ECS can pull images from ECR
AWS provider ~> 6.0
Anthropic first-time-use form submitted for the AWS account (see below) — this module sets BEDROCK_ENABLED = true, and Runlayer Assistant always routes through Bedrock

Anthropic model access. Anthropic requires a use case details form before its models can be invoked in an AWS account, plus an accepted model agreement. You need this when the deployment invokes Anthropic models on Bedrock — typically BEDROCK_ENABLED=true (Runlayer Assistant platform inference and optional Bedrock agent models). With BEDROCK_ENABLED=false, Runlayer Assistant binds an org AI provider instead; skip this step unless you also enable Bedrock inference elsewhere (for example BEDROCK_ANTHROPIC_MODELS_ENABLED for custom agents).The backend does both for you at startup and on login, in the account the Bedrock calls come from, using the model-access IAM permissions your deployment grants. Four settings describe the deployment on the form — BEDROCK_MODEL_ACCESS_COMPANY_NAME (defaults to Runlayer, the operator of the software making the calls), BEDROCK_MODEL_ACCESS_COMPANY_WEBSITE, BEDROCK_MODEL_ACCESS_INDUSTRY and BEDROCK_MODEL_ACCESS_INTENDED_USERS. Override them if you run this install yourself. They are never derived from your data: the form is submit-once, so a guessed answer would be permanent.Set BEDROCK_AUTO_MODEL_ACCESS=false to turn this off and do it by hand instead: Bedrock console → Model catalog → any Anthropic model → Submit use case details. Do the same if your deployment role predates the model-access permissions — the backend logs exactly which actions it is missing. AWS accepts the form once per account, or once at your AWS Organization’s management account, which member accounts inherit.Deploying outside the US? Also set RUNLAYER_ASSISTANT_BEDROCK_MODEL to your geography’s inference profile, for example au.anthropic.claude-opus-4-6-v1 in ap-southeast-2.Access takes up to 15 minutes to propagate. Until it does — or if this is skipped entirely — Bedrock-backed agents fail with Model use case details have not been submitted for this account; see troubleshooting for the CLI checks and Region caveats.

Values from Runlayer

Runlayer provides during onboarding:

auth_client_id — WorkOS/Auth client ID
auth_api_key — treat as a secret; pass via TF_VAR_auth_api_key, never commit
Module version to pin (for example v19.12.1)
Confirmation that your account is allowlisted for S3 module downloads and ECR image pulls

Quick Start

1. Create a working directory with a root module that references the published archive:

terraform {
  required_version = ">= 1.9"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }

  # Recommended for production
  backend "s3" {
    bucket = "your-terraform-state-bucket"
    key    = "runlayer/production/terraform.tfstate"
    region = "us-east-1"
  }
}

locals {
  region      = "us-east-1"
  account     = "123456789012"
  domain_name = "ai.yourcompany.com"
}

provider "aws" {
  region = local.region
}

provider "aws" {
  alias  = "route53"
  region = local.region
  # For cross-account DNS, add assume_role { role_arn = "..." } here
}

variable "auth_api_key" {
  type      = string
  sensitive = true
}

module "runlayer_infrastructure" {
  # Pin the module version Runlayer provides
  source = "s3::https://s3.amazonaws.com/runlayer-infrastructure-modules/terraform-ecs/v19.12.1/terraform-ecs-v19.12.1.tar.gz"

  providers = {
    aws         = aws
    aws.route53 = aws.route53
  }

  project     = "ecs"
  environment = "production"
  region      = local.region
  account     = local.account
  domain_name = local.domain_name

  auth_client_id = "client_REPLACE_ME" # from Runlayer
  auth_api_key   = var.auth_api_key

  enable_acm_dns_validation = true
  hosted_zone_name          = local.domain_name
  create_dns_records        = true
}

output "application_url" {
  value = module.runlayer_infrastructure.application_url
}

2. Deploy:

export TF_VAR_auth_api_key="<key from Runlayer>"

terraform init   # downloads the module from S3
terraform plan
terraform apply  # typically 25–40 minutes on first apply

Provider wiring is required: always pass aws and aws.route53 into the module, even when DNS lives in the same account.

Delivery details

Terraform module (S3)

Module archives are published to:

s3://runlayer-infrastructure-modules/terraform-ecs/vX.Y.Z/terraform-ecs-vX.Y.Z.tar.gz

Terraform source form:

source = "s3::https://s3.amazonaws.com/runlayer-infrastructure-modules/terraform-ecs/vX.Y.Z/terraform-ecs-vX.Y.Z.tar.gz"

To upgrade, bump the version in source, then:

terraform init -upgrade
terraform plan
terraform apply

Container images (ECR)

By default the module pulls Runlayer images from CustomerDistribution ECR:

088332244652.dkr.ecr.<region>.amazonaws.com/runlayer/backend:<app_version>
088332244652.dkr.ecr.<region>.amazonaws.com/runlayer/frontend:<app_version>
088332244652.dkr.ecr.<region>.amazonaws.com/runlayer/worker:<app_version>

The module pins a default app_version. Override it, or supply your own image map:

# Pin a Runlayer release (mutually exclusive with ecr_repositories)
app_version = "1.28.162"

# OR use your own registry / mirror (backend, frontend, worker all required)
ecr_repositories = {
  backend  = "123456789012.dkr.ecr.us-east-1.amazonaws.com/runlayer/backend:1.28.162"
  frontend = "123456789012.dkr.ecr.us-east-1.amazonaws.com/runlayer/frontend:1.28.162"
  worker   = "123456789012.dkr.ecr.us-east-1.amazonaws.com/runlayer/worker:1.28.162"
}

Validation rules (enforced by the module):

URIs must be public ECR (public.ecr.aws/...) or private ECR (account.dkr.ecr.region.amazonaws.com/...)
Every URI must include an explicit tag or @sha256: digest — no implicit latest
app_version and ecr_repositories are mutually exclusive

The module grants its ECS task execution role permission to pull from Runlayer’s CustomerDistribution registry. Private repositories in your deployment account are pullable through the standard execution role. Repositories in another AWS account need both task-role permission and a repository policy granting your account pull access.

Configuration options

Required inputs

Variable	Description	Example
`account`	AWS account ID	`"123456789012"`
`region`	AWS region	`"us-east-1"`
`domain_name`	Hostname for HTTPS access	`"ai.yourcompany.com"`
`auth_client_id`	Auth client ID from Runlayer	`"client_..."`
`auth_api_key`	Auth API key from Runlayer (sensitive)	via `TF_VAR_auth_api_key`

Smart production-ready defaults include:

Database: Aurora PostgreSQL Serverless v2, private subnets, automated backups
Cache: ElastiCache Redis in private subnets
Security: Public ALB by default; private DB/cache; Secrets Manager for app secrets
SSL: Automatic wildcard certificate lookup; set enable_acm_dns_validation = true to create + validate a cert via Route53
Scaling: Backend default 4096 CPU / 8192 MB; frontend 256 CPU / 512 MB; auto-scaling enabled
Network: Multi-AZ VPC with public/private subnets (IPv6 on by default; set enable_ipv6 = false for IPv4-only)
Monitoring: CloudWatch logs for all services

Optional configuration

Database Configuration

database_name     = "anysource"
database_username = "postgres"
database_config = {
  engine_version      = "16"
  min_capacity        = 4
  max_capacity        = 32
  publicly_accessible = false
  backup_retention    = 30
}

Bring Your Own Database / Cache

Skip Aurora and/or ElastiCache when you operate PostgreSQL and Redis/Valkey yourself. Postgres and Redis can be configured independently.

external_database = {
  host            = "postgres.internal.example.com"
  reader_host     = "postgres-reader.internal.example.com" # optional
  port            = 5432
  database        = "runlayer"
  username        = "runlayer"
  ssl_mode        = "require"
}
external_database_password = var.external_db_password

external_redis = {
  host        = "valkey.internal.example.com"
  port        = 6379
  tls_enabled = true
}
external_redis_password = var.external_redis_password

ECS tasks receive POSTGRES_* env vars and Secrets Manager entries for PLATFORM_DB_PASSWORD and REDIS_URL. Ensure private subnets can reach your endpoints. For Kubernetes, see the Runlayer Operator database and Redis contract.

Security Configuration

alb_access_type = "public"            # "public" or "private"
alb_allowed_cidrs = [
  "0.0.0.0/0"                         # tighten for production
]
alb_allowed_ipv6_cidrs = ["::/0"]

# WAF IP allowlisting (recommended for production)
waf_enable_ip_allowlisting = true
waf_allowlist_ipv4_cidrs = [
  "203.0.113.0/24",
  "198.51.100.42/32",
]
waf_allowlist_ipv6_cidrs = [
  "2001:db8::/48",
]

# SSL options (choose one):

# Option 1: Look up existing wildcard certificate (DEFAULT)
hosted_zone_name = "prod.yourcompany.com"

# Option 2: Create new certificate with DNS validation
enable_acm_dns_validation = true
hosted_zone_name          = "prod.yourcompany.com"

# Option 3: Provide a certificate ARN
ssl_certificate_arn = "arn:aws:acm:us-east-1:123456789012:certificate/xxx"

# DNS record control
create_dns_records = true  # Route53 ALIAS to ALB (default: false)

Dual ALB Setup (Split-Horizon DNS)

enable_dual_alb = true

# Optional: existing private hosted zone
private_hosted_zone_id = "Z1234567890ABC"
private_hosted_zone_vpc_id = "vpc-1234567890abcdef0"
private_hosted_zone_additional_vpc_ids = [
  "vpc-0987654321fedcba0",
]

alb_internal_allowed_cidrs = [
  "10.200.0.0/16",  # Corporate VPN
]
alb_internal_allowed_ipv6_cidrs = [
  "fd00::/64",
]

Use case: public access (for example ChatGPT / external integrations) plus private network access on the same hostname via split-horizon DNS.

Public DNS → public ALB
Private DNS → internal ALB
ECS services register with both ALBs
WAF applies only to the public ALB

VPC Peering for Cross-VPC Connectivity

Security note: every peering connection must set peer_owner_id. The module validates ownership before accepting the connection.

vpc_peering_connections = {
  "customer-vpc" = {
    peering_connection_id = "pcx-0abc123def456"
    peer_vpc_cidr         = "172.16.0.0/16"
    peer_owner_id         = "123456789012"   # REQUIRED
    peer_region           = "us-east-1"      # optional
  }
}

VPC peering only applies when the module creates the VPC (not with existing_vpc_id).

Service Scaling

Defaults already set production-ready CPU/memory. To override, replace the full services_configurations map (partial maps are not merged):

services_configurations = {
  "backend" = {
    name              = "backend"
    path_pattern      = ["/api/*", "/docs*", "/redoc*", "/.well-known*"]
    health_check_path = "/api/v1/utils/health-check/"
    container_port    = 8000
    host_port         = 8000
    port              = 8000
    priority          = 10
    desired_count     = 3
    min_capacity      = 2
    max_capacity      = 10
    cpu               = 2048
    memory            = 4096
    cpu_auto_scalling_target_value    = 70
    memory_auto_scalling_target_value = 80
  }

  "frontend" = {
    name              = "frontend"
    path_pattern      = ["/*"]
    health_check_path = "/"
    container_port    = 80
    host_port         = 80
    port              = 80
    priority          = 20
    desired_count     = 2
    cpu               = 512
    memory            = 1024
  }
}

Reserve backend.priority + 1 for the /mcp alias listener rule (module validation enforces this).

Network Configuration

vpc_cidr        = "10.0.0.0/16"
region_az       = ["us-east-1a", "us-east-1b", "us-east-1c"]
public_subnets  = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
private_subnets = ["10.0.4.0/24", "10.0.5.0/24", "10.0.6.0/24"]
enable_ipv6     = true   # set false for IPv4-only networks

Use an existing VPC — all three variables must be provided together:

existing_vpc_id             = "vpc-xxxxx"
existing_private_subnet_ids = ["subnet-xxxxx", "subnet-yyyyy", "subnet-zzzzz"]
existing_public_subnet_ids  = ["subnet-aaaaa", "subnet-bbbbb", "subnet-ccccc"]

Private subnets need NAT (or VPC endpoints) for ECR pulls; public subnets need an internet gateway for the ALB. For topology options, see Networking.

Monitoring & Alerting

enable_monitoring = true
slack_channel_id  = "C1234567890"
slack_team_id     = "T1234567890"

# ECS Container Insights: null uses environment default
# (production → "enabled", staging/development → "disabled")
container_insights = "enabled"

Automatic CloudWatch alarms cover: ECS CPU/memory, RDS, Redis, ALB latency/unhealthy targets/5XX, and VPC flow logs.

rds_alarm_config = {
  FreeableMemory = { period = 300, threshold = 268435456, unit = "Bytes" }
  DiskQueueDepth = { period = 300, threshold = 5, unit = "Count" }
  WriteIOPS      = { period = 300, threshold = 1000, unit = "Count" }
  ReadIOPS       = { period = 300, threshold = 1000, unit = "Count" }
  Storage        = { period = 300, threshold = 107374182400, unit = "Bytes" }
}

alb_5xx_alarm_period    = 300
alb_5xx_alarm_threshold = 1

Optional feature flags

Runlayer Deploy is always enabled by the ECS module.

enable_runlayer_agents            = true
enable_runlayer_agentcore_runtime = true
enable_runlayer_tool_guard        = true

enable_audit_log_kinesis    = true
audit_log_write_target      = "kinesis"
enable_audit_log_s3_archive = true
audit_log_kinesis_consumer_config = {
  enabled       = true
  desired_count = 1
}

Agent Sandbox (Optional)

# Separate Sentry DSN for sandbox errors (does not reuse backend sentry_dsn)
runlayer_agent_sandbox_sentry_dsn = var.agent_sandbox_sentry_dsn

By default, Agent Sandbox routes LLM calls through the backend Anthropic proxy. To use OpenAI or an OpenAI-compatible gateway, add a provider in Settings → AI Providers (no Terraform change needed).This Terraform path provisions the ECS / AgentCore sandbox. In-cluster kubernetes-sigs Agent Sandbox (sandboxMode: k8s, gVisor or Kata on the nodes) is operator/GKE — see Runlayer Operator — K8s Agent Sandbox.Runlayer Assistant always runs on Bedrock in this account — it ignores Settings → AI Providers by design, so it works without configuring a provider. Model access is handled as described above; this module exposes it as bedrock_auto_model_access, bedrock_model_access_company_name, bedrock_model_access_company_website, bedrock_model_access_industry and bedrock_model_access_intended_users.

Secrets management

All application secrets live in AWS Secrets Manager in your account. The module creates two primary secrets (plus an optional LLM gateway secret):

Secret / key	Where stored	Source
`SECRET_KEY`	Restricted app-keys secret (`restricted/...-app-keys-<suffix>`)	Auto-generated (or from `secret_key`)
`MASTER_SALT`	Restricted app-keys secret	Auto-generated (or from `master_salt`)
`PLATFORM_DB_PASSWORD`	App secrets secret (`<project>-<env>-<suffix>`)	Auto-generated (or from `external_database_password`)
`REDIS_URL`	App secrets secret	Auto-generated (or from external Redis settings)
`AUTH_API_KEY`	App secrets secret	From `auth_api_key` / `TF_VAR_auth_api_key`
`MCP_CATALOG_API_KEY`	App secrets secret	From `mcp_catalog_api_key` (optional)
`SENTRY_*`	App secrets secret	Optional (`sentry_dsn` or WorkOS Vault via Relay)
`LLM_GATEWAY_RUNLAYER_API_KEY`	Separate `restricted/...-llm-gateway-<suffix>` secret	From `llm_gateway_runlayer_api_key` when `enable_llm_gateway = true`

Design notes:

SECRET_KEY and MASTER_SALT are isolated in the restricted secret so only privileged task roles can read them.
The app secret and restricted secret share the same random name suffix to avoid recreate collisions during Secrets Manager recovery windows.
Prefer TF_VAR_* / a secrets backend for sensitive inputs — do not commit API keys to git.
After deploy, rotate non-key values with Secrets Manager (then force a new ECS deployment so tasks pick up the new version). Rotate SECRET_KEY/MASTER_SALT via secret_key/master_salt instead — Terraform reverts out-of-band edits to the restricted secret on the next apply.

# Inspect secret names created by the module
terraform output app_secrets_name
terraform output restricted_app_keys_secret_name

# Example: update a non-key application secret after deploy
aws secretsmanager update-secret \
  --secret-id "$(terraform output -raw app_secrets_name)" \
  --secret-string file://updated-secrets.json

# Roll tasks so they remount the new secret version
aws ecs update-service --cluster "$(terraform output -raw ecs_cluster_name)" \
  --service backend --force-new-deployment

Module outputs (attributes)

After apply, useful outputs include:

Output	Description
`application_url`	Primary `https://` URL
`alb_dns_name` / `alb_zone_id`	Public ALB DNS + hosted-zone ID
`public_alb_dns_name` / `internal_alb_dns_name`	Dual-ALB DNS names (when enabled)
`privatelink_service_name`	VPC endpoint service name (when PrivateLink enabled)
`ecs_cluster_arn` / `ecs_cluster_name`	ECS cluster identifiers
`vpc_id` / `private_subnet_ids`	Network IDs
`task_role_arn` / `ecs_task_execution_role_arn`	IAM roles
`app_secrets_name`	Application Secrets Manager secret name
`restricted_app_keys_secret_name` / `restricted_app_keys_secret_arn`	Restricted key material
`llm_gateway_base_url`	LLM gateway base URL (when enabled)
`runlayer_tool_guard_enabled` / `runlayer_tool_guard_endpoint_url`	ToolGuard status

terraform output application_url
curl "$(terraform output -raw application_url)/api/v1/utils/health-check/"

Deployment

Automated database setup

Database initialization is automated during apply: What happens automatically:

Migration task waits for PostgreSQL, then runs alembic upgrade head
Backend services only roll out after migrations succeed (Terraform waits up to 30 minutes by default)
Setup activity is logged to CloudWatch under anysource-backend-migration-logs-<environment>
Re-running terraform apply after interruption is safe (idempotent + advisory lock)

Verify

terraform output application_url
# Open the URL — login page should load over TLS
# Sign-in / SSO is coordinated with Runlayer against your auth_client_id

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

alb_access_type = "private"
alb_allowed_cidrs = ["10.0.0.0/8"]

waf_enable_ip_allowlisting = true
waf_allowlist_ipv4_cidrs = [
  "10.100.0.0/16",
  "10.200.0.0/16",
]

database_config = {
  publicly_accessible = false
  backup_retention    = 30
}

High availability production

database_config = {
  min_capacity = 8
  max_capacity = 64
}

redis_num_cache_clusters         = 2
redis_automatic_failover_enabled = true
redis_multi_az_enabled           = true

Development environment

environment = "development"
database_config = {
  min_capacity     = 2
  max_capacity     = 4
  backup_retention = 1
}
enable_monitoring = false

Troubleshooting

terraform init cannot download the module

Confirm your AWS credentials can s3:GetObject on runlayer-infrastructure-modules and that Runlayer allowlisted your account or IAM principal. Contact support@runlayer.com if access was not provisioned during onboarding.

ECS tasks cannot pull images

Confirm ECR pull access to 088332244652 (CustomerDistribution)
Private subnets need NAT or ECR VPC endpoints
Check ECS service events for CannotPullContainerError / AccessDeniedException

SSL Certificate Issues

Wildcard lookup fails (default behavior):

aws acm list-certificates --query "CertificateSummaryList[?contains(DomainName, '*')]"

DNS validation fails (when enable_acm_dns_validation = true):

aws acm describe-certificate --certificate-arn your-cert-arn
dig _acme-challenge.your-domain.com CNAME

For cross-account DNS, confirm the aws.route53 provider assume_role can write validation records.

Application Not Accessible

aws elbv2 describe-target-health --target-group-arn your-tg-arn
aws ecs describe-services --cluster "$(terraform output -raw ecs_cluster_name)"

Migration task failures

Check CloudWatch anysource-backend-migration-logs-<environment>. Re-running terraform apply is safe — the migration uses an advisory lock and rolls back on failure.

High Costs

Use environment = "development" for testing
Reduce database min_capacity / max_capacity
Lower service desired_count and CPU/memory
Set shorter backup_retention
Consider single_nat_gateway = true for non-prod

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

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Overview

Prerequisites

Quick Start

Delivery details

Terraform module (S3)

Container images (ECR)

Configuration options

Required inputs

Optional configuration

Secrets management

Module outputs (attributes)

Deployment

Automated database setup

Verify

Architecture

Cost estimation

Common use cases

Private enterprise deployment

High availability production

Development environment

Troubleshooting

ECS vs EKS: which to choose?

Next Steps

EKS + Terraform

Runlayer Operator

​Overview

​Prerequisites

​Quick Start

​Delivery details

​Terraform module (S3)

​Container images (ECR)

​Configuration options

​Required inputs

​Optional configuration

​Secrets management

​Module outputs (attributes)

​Deployment

​Automated database setup

​Verify

​Architecture

​Cost estimation

​Common use cases

​Private enterprise deployment

​High availability production

​Development environment

​Troubleshooting

​ECS vs EKS: which to choose?

​Next Steps

EKS + Terraform

Runlayer Operator

Overview

Prerequisites

Quick Start

Delivery details

Terraform module (S3)

Container images (ECR)

Configuration options

Required inputs

Optional configuration

Secrets management

Module outputs (attributes)

Deployment

Automated database setup

Verify

Architecture

Cost estimation

Common use cases

Private enterprise deployment

High availability production

Development environment

Troubleshooting

ECS vs EKS: which to choose?

Next Steps