ECS Deployment Guide

This guide deploys Runlayer into your AWS account. Start with the ECS overview and complete ECS prerequisites, including Runlayer credentials, AWS identity, state storage, DNS, egress, and Bedrock access. The example creates a new VPC, a public HTTPS load balancer, Aurora PostgreSQL, and ElastiCache Redis. For existing infrastructure or private access, select the networking and configuration inputs before applying. This guide explicitly selects Distribution-backed feature flags with openfeature_provider = "flagd". Obtain a Distribution reader key registered for this deployment from Runlayer before applying. The module’s application default is still WorkOS; setting only the Distribution key and URL does not switch providers.

Quick Start

1. Create the root configuration

Create a working directory and save the following as main.tf. Replace the account, hostname, parent hosted zone, state bucket, auth client ID, and company details. Pin the module release agreed with Runlayer; this example uses v33.1.0, whose default app version is 1.28.1078.

mkdir runlayer-ecs
cd runlayer-ecs

terraform {
  required_version = ">= 1.11.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.64.0, < 7.0.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.9"
    }
  }

  backend "s3" {
    bucket       = "your-existing-terraform-state-bucket"
    key          = "runlayer/production/terraform.tfstate"
    region       = "us-east-1"
    encrypt      = true
    use_lockfile = true
  }
}

locals {
  region           = "us-east-1"
  account          = "123456789012"
  domain_name      = "ai.example.com"
  hosted_zone_name = "example.com"
  project          = "ecs"
  environment      = "production"
}

provider "aws" {
  region = local.region
}

provider "aws" {
  alias  = "route53"
  region = local.region
}

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

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

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

module "runlayer_infrastructure" {
  source = "s3::https://s3.amazonaws.com/runlayer-infrastructure-modules/terraform-ecs/v33.1.0/terraform-ecs-v33.1.0.tar.gz"

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

  project     = local.project
  environment = local.environment
  region      = local.region
  account     = local.account
  domain_name = local.domain_name

  auth_client_id      = "client_REPLACE_ME"
  auth_api_key        = var.auth_api_key
  mcp_catalog_api_key = var.mcp_catalog_api_key

  distribution_api_key = var.distribution_api_key
  distribution_api_url = "https://distribution.prod.runlayer.com"
  openfeature_provider = "flagd"

  enable_acm_dns_validation = true
  hosted_zone_name          = local.hosted_zone_name
  create_dns_records        = true

  # Replace with your organization before the first startup.
  bedrock_auto_model_access            = true
  bedrock_model_access_company_name    = "Example Corp"
  bedrock_model_access_company_website = "https://example.com"
  bedrock_model_access_industry        = "Technology"
  bedrock_model_access_intended_users  = 100

  wait_for_ecs_steady_state = true
  ecs_service_wait_timeout  = "30m"
}

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

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

output "backend_log_group_name" {
  value = "anysource-backend-logs-${local.project}-${local.environment}"
}

output "migration_log_group_name" {
  value = "anysource-backend-migration-logs-${local.project}-${local.environment}"
}

Always pass both aws and aws.route53, including when DNS lives in the same account. Cross-account DNS also needs the DNS role and zone ID described in networking. Terraform marks only five module inputs as required because they have no defaults. This guide also requires the catalog credential and the registered Distribution reader key. Confirm outbound HTTPS to distribution.prod.runlayer.com before startup. Add your selected database, network, security, and optional-feature inputs to this configuration before continuing.

2. Supply credentials

Keep the AWS credential environment from prerequisites. Provide the secret inputs through your secret manager or environment. For an interactive Bash shell, these prompts avoid putting values in shell history:

read -r -s -p "WorkOS API key: " TF_VAR_auth_api_key
printf '\n'
export TF_VAR_auth_api_key
read -r -s -p "MCP Catalog API key: " TF_VAR_mcp_catalog_api_key
printf '\n'
export TF_VAR_mcp_catalog_api_key
read -r -s -p "Distribution reader key: " TF_VAR_distribution_api_key
printf '\n'
export TF_VAR_distribution_api_key
aws sts get-caller-identity

Do not commit .terraform/, *.tfstate*, *.tfplan, or files containing secrets. Commit .terraform.lock.hcl after initialization.

3. Initialize, validate, and plan

Before planning, review the selected module’s external programs and provisioners. Sentry Relay is enabled by default and its external data source can authenticate with your WorkOS API key and read Relay secrets during the plan. Confirm this credential use and runner access first; see Sentry Relay Vault integration. local-exec provisioners run during resource creation/destruction, not an ordinary plan, while external data sources can run during planning or be deferred to apply.

terraform init
terraform fmt -check
terraform validate
terraform plan -out=runlayer.tfplan

Review the plan’s account, region, network, public/private access, database/cache configuration, optional resources, and cost implications. Resolve errors before applying. A saved plan contains sensitive data even when terminal output redacts it. For an existing deployment with an older provider selection, review the module changelog and use terraform init -upgrade to update the lockfile before planning.

4. Apply

terraform apply runlayer.tfplan

The module runs a separate ECS migration task and waits for it to succeed before rolling out application services. Migration logs are in anysource-backend-migration-logs-<project>-<environment>. The migration wait defaults to 30 minutes. This example sets wait_for_ecs_steady_state = true; the module default is false. Even with waiting enabled, complete the checks below: infrastructure readiness does not prove login or connector workflows work.

Verify

Run these commands from the root configuration directory, with the same AWS profile and region:

aws ecs wait services-stable \
  --cluster "$(terraform output -raw ecs_cluster_name)" \
  --services backend-service frontend-service worker-service mcp-exec-worker-service

aws ecs describe-services \
  --cluster "$(terraform output -raw ecs_cluster_name)" \
  --services backend-service frontend-service worker-service mcp-exec-worker-service \
  --query '{failures:failures,services:services[].{name:serviceName,desired:desiredCount,running:runningCount,pending:pendingCount,rollouts:deployments[].{status:status,state:rolloutState,reason:rolloutStateReason}}}' \
  --output json

curl --fail --show-error --silent "$(terraform output -raw application_url)/" --output /dev/null
curl --fail --show-error --silent "$(terraform output -raw application_url)/api/v1/utils/health-check/"

Check that there are no service lookup failures, running counts match nonzero desired counts, pending counts are zero, and the primary deployments show COMPLETED. The AWS waiter has its own timeout; a timeout requires inspecting events and logs. For a private ALB, run HTTP checks from a machine with the required private routing and DNS. Then verify the user journey:

Open terraform output -raw application_url, confirm TLS is valid, and sign in through the configured SSO/WorkOS flow.
Confirm the MCP catalog loads. A catalog 503 can indicate a missing API key; 401 can indicate a wrong key or catalog URL.
Configure an approved test connector, connect an MCP client, and make a harmless tool call. Confirm its session/audit record appears.
Exercise each feature you enabled: an agent run, ToolGuard scan, or AI Watch package discovery, as applicable. Confirm optional services and load-balancer targets are healthy too.

A reachable login page alone is not a successful deployment.

Troubleshooting

Module or image access denied

For terraform init, confirm the deployment identity can read the versioned archive in runlayer-infrastructure-modules. For CannotPullContainerError, check ECS events, ECR access to account 088332244652, and the ECR/S3 network paths. Contact Runlayer support if onboarding access is missing.

Migration task failures

aws logs tail "$(terraform output -raw migration_log_group_name)" --since 30m

If the first apply failed before root outputs were saved, substitute anysource-backend-migration-logs-ecs-production for the example configuration, or use your actual project and environment. Check the migration task’s stopped reason, database connectivity, image permissions, and the AWS CLI credentials inherited by Terraform. After correcting the cause, review a new plan before applying again. Do not disable state locking or force-unlock while another run may still own the lock.

Application not accessible

aws ecs describe-services \
  --cluster "$(terraform output -raw ecs_cluster_name)" \
  --services backend-service frontend-service \
  --query '{failures:failures,services:services[].{name:serviceName,events:events[:5]}}'
aws logs tail "$(terraform output -raw backend_log_group_name)" --since 30m

Check DNS, ACM certificate status, ALB security groups/WAF, and target health in the EC2 load balancer console. For failed ACM validation, inspect the certificate’s DomainValidationOptions and verify its exact CNAME name and value in authoritative DNS. Check egress symptoms, Bedrock access, and your feature’s configuration. AgentCore behind WAF needs the private network path; ToolGuard needs working GPU bootstrap and capacity.

Next Steps

The following sections retain their existing links and point to the focused guides.

Prerequisites

See ECS prerequisites.

Private connection provisioning

See private connection provisioning. Connection configuration revision 2 is separate from module releases such as v33.1.0.

Container images (ECR)

See images and versions. Image overrides are described in Updates.

Deployment

Follow Quick Start, then Verify.

Automated database setup

See the migration and startup sequence.

Overview

See the ECS overview.

Architecture

See Architecture.

Cost estimation

See capacity and cost.

Common use cases

See configuration examples.

Private enterprise deployment

See private access choices.

High availability production

See high availability configuration.

Development environment

See development configuration.

ECS vs EKS: which to choose?

See Deployment Overview.

​Quick Start

​1. Create the root configuration

​2. Supply credentials

​3. Initialize, validate, and plan

​4. Apply

​Verify

​Troubleshooting

​Module or image access denied

​Migration task failures

​Application not accessible

​Login works but optional features fail

​Next Steps

​Related configuration

​Prerequisites

​Private connection provisioning

​Private CA certificates

​Distribution configuration

​Delivery details

​Configuration options

​Secrets management

​Module outputs (attributes)

​Naming constraints

​Required inputs

​Optional configuration

​Optional services

​Terraform module (S3)

​Container images (ECR)

​Deployment

​Automated database setup

​Overview

​Architecture

​Cost estimation

​Common use cases

​Private enterprise deployment

​High availability production

​Development environment

​ECS vs EKS: which to choose?

Quick Start

1. Create the root configuration

2. Supply credentials

3. Initialize, validate, and plan

4. Apply

Verify

Troubleshooting

Module or image access denied

Migration task failures

Application not accessible

Login works but optional features fail

Next Steps

Related configuration

Prerequisites

Private connection provisioning

Private CA certificates

Distribution configuration

Delivery details

Configuration options

Secrets management

Module outputs (attributes)

Naming constraints

Required inputs

Optional configuration

Optional services

Terraform module (S3)