Skip to main content
Choose the network, DNS, and access settings before following the ECS deployment guide. Add these inputs inside module "runlayer_infrastructure" in your root configuration. Merge examples with your existing values; do not declare the same input twice.

DNS and TLS

domain_name is the application hostname, such as ai.example.com. hosted_zone_name is the existing authoritative Route 53 zone, such as example.com; they are usually different. The deployment guide creates and validates *.example.com in ACM and creates the application DNS record in that zone. For DNS in another account, configure aws.route53 with the DNS account role and set cross_account_hosted_zone_id to that zone’s ID. Always pass both provider aliases to the module. The certificate must be in the workload account and ALB region. For DNS outside Route 53, supply an issued ssl_certificate_arn, leave enable_acm_dns_validation = false and create_dns_records = false, then create the application DNS record yourself using the module’s alb_dns_name output. Complete ACM validation with your DNS provider before deploying. Choose one certificate strategy:

Access choices

Private ALBs and PrivateLink do not remove outbound requirements. AWS VPC endpoints cover specific AWS APIs; WorkOS, AuthKit, catalog, and other external services still need outbound HTTPS. Review egress requirements.

Network Configuration

Use an existing VPC — all three variables must be provided together:
Private subnets need ECR/S3 endpoints or NAT for image pulls, plus NAT or another outbound HTTPS path for the external hosts in Self-Hosted Egress Requirements. Public subnets need an internet gateway for the ALB. Pass one public subnet per Availability Zone. Multiple subnets in the same AZ cause CreateLoadBalancer to fail with A load balancer cannot be attached to multiple subnets in the same Availability Zone. Subnet size can be small (for example /26) as long as the ALB has free IPs (~8+). Multiple ALBs may share the same public subnets. For topology options, see Networking.

Security Configuration

waf_webhook_allowlist_ipv4_cidrs and waf_webhook_allowlist_ipv6_cidrs default to []. They admit the specified request-origin IPs only for POST agent webhook invocation: /api/v1/agents/{uuid}/webhooks/{token} and the legacy /api/v1/assistants/{uuid}/webhooks/{token}, with an optional trailing slash. Paths are URL-decoded and normalized before matching. Webhook management routes and other methods receive no additional access; existing general allowlists and public-path exemptions still apply. Nonempty lists require waf_enable_ip_allowlisting = true; nonempty IPv6 lists also require enable_ipv6 = true. Invalid configurations fail planning; empty lists remain valid when either feature is disabled. General allowlist CIDRs remain required when allowlisting is enabled. Entries must be valid IPv4 CIDRs with prefix lengths 1–32 or IPv6 CIDRs with prefix lengths 1–128. The caller maintains these ranges; the module does not fetch vendor IP lists. Managed WAF rules and webhook authentication still apply. These lists cover invocation routes across agents, so review the admitted ranges, webhook credentials/signing, and execution identity with your security team before activation. ALB security groups must also permit the integration’s source IPs. When AgentCore is enabled, WAF IP allowlisting requires AgentCore VPC mode with PrivateLink. PUBLIC mode has no stable source IP to allowlist. Configure this before deployment:
The consumer subnets need the AgentCore egress paths. See AgentCore with WAF.

Dual ALB Setup (Split-Horizon DNS)

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 only applies when the module creates the VPC (not with existing_vpc_id). Expose Runlayer to consumer VPCs with an endpoint service:
Expose the child module output in your root configuration:
After apply, use terraform output -raw privatelink_service_name to create consumer interface endpoints. Accept endpoint requests when acceptance is required and configure consumer DNS, routing, and security groups.

Outbound private connections for Runlayer Deploy

These connect your deployed MCPs to private upstream systems. Select the connection types you need:
Upgrade the module with the application: each module release selects the matching router, endpoint, and connector bundle. Enable tunnels only with a compatible application release. Upgrade the application before the module; on rollback, restore the previous module configuration before the application. See Updates.

Private connection provisioning

ECS private connections reconcile asynchronously. Revision 2 is an internal private-connection configuration marker, separate from the ECS module release (for example, v33.1.0). This migration guidance applies to existing connections, not initial platform installation. Existing Deploy PrivateLink connections upgrade to connection configuration revision 2, adding connection-owned access security groups while retaining the existing endpoint and legacy security group. Wait for reconciliation before creating or redeploying an MCP deployment that uses the connection. Existing running deployments retain their legacy access rules; redeployment switches them to access-SG attachment. Each deployment supports up to four private connections. RUNLAYER_PRIVATE_CONNECTION_TERRAFORM_TIMEOUT_SECONDS defaults to 1800 and must be a positive finite number. Set it through additional_backend_env_vars to override the shared deadline for Terraform init, apply/destroy, and output commands. It does not change ordinary MCP deployment timeouts. Failed reconciliation preserves the connection’s prior usable state and is retried automatically up to 3 times, at least 15 minutes apart; if it still fails, contact Runlayer support to inspect and recover the upgrade before retrying the deployment.

Private CA certificates

To trust MCP servers or HTTPS proxies whose certificates use your private CA, pass the CA certificate bundle to the ECS module:
The file may concatenate multiple PEM certificate blocks. Include CA certificates only—never private keys. The module combines them with the public roots already in the Runlayer image and configures the backend, shared worker, and MCP execution worker to use the combined bundle. Frontend and migration tasks are intentionally unchanged because neither connects to customer MCP servers or customer-managed private-CA HTTPS endpoints. Changing the file and applying Terraform rolls the affected ECS tasks. The tasks start only after an init container validates and writes the bundle.