Skip to main content
Use these examples when preparing your ECS deployment, or when updating an existing installation. All input snippets belong inside the module block unless marked as root outputs. Merge examples into your existing configuration. The inputs reference is the full variable contract. Networking and optional features have their own guides.

Naming constraints

These values are used in AWS resource names (ElastiCache replication group IDs, secrets, IAM, etc.) and are validated by the module: Generated names follow <project>-<environment>-…. Example: project = "acme", environment = "staging" → Redis replication group acme-staging-redis.

Database Configuration

Managed Aurora is always PostgreSQL Serverless v2 (db.serverless). There is no provisioned instance-class input (db.r6g.large, etc.). Size the cluster with Aurora Capacity Units (ACUs):
Pick ACU values supported for Aurora PostgreSQL Serverless v2 in your region. For a database you operate yourself (any size or engine), use external_database instead. To diagnose lock contention, set database_config.log_lock_waits = true; it applies immediately without a reboot. Logs use the existing PostgreSQL CloudWatch export and deadlock_timeout threshold (engine default: one second), which the module leaves unchanged. This setting applies only to managed Aurora.

Customer-managed Aurora encryption key

Set this optional input before creating the managed Aurora cluster:
Omit it or set null to preserve existing key selection. Storage encryption remains enabled. This input is ignored when external_database is set; it does not configure Performance Insights, Secrets Manager, or CloudWatch Logs encryption. Supply the key ARN (...:key/<id>). Alias ARNs and bare key IDs are rejected. RDS resolves an alias to its key ARN, which would otherwise cause subsequent Terraform plans to propose cluster replacement. Use an enabled symmetric encryption key in the cluster’s AWS Region. The key policy and deployment principal’s permissions must allow RDS to use the key, including creating its KMS grant. The module does not create or modify the supplied key or its policy. See Aurora KMS key management. Automated backups and snapshots (including final snapshots) inherit the cluster’s key. Retain the key and required access for as long as the cluster or any backup needs it. Aurora cannot change an existing cluster’s encryption key in place. Setting a different key on an existing deployment can plan cluster replacement; migrate to a new cluster instead of applying that replacement to a live database. To migrate using snapshots, copy a manual snapshot with the new key, then restore a new cluster from that copy. When using snapshot_identifier, retain access to the snapshot’s encryption key and use the copied snapshot’s key ARN here. See Aurora encryption.

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.
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.

Redis / ElastiCache

Managed Redis (skipped when external_redis is set): redis_engine needs module v49.0.0 or later. On an older release, terraform plan fails with Unsupported argument.

Service Scaling

Defaults already set production-ready CPU/memory. To override, replace the full services_configurations map (partial maps are not merged):
min_capacity / max_capacity control the running fleet: Application Auto Scaling owns each service’s live desired_count, and Terraform ignores it after the service is created, so desired_count only seeds a brand-new service. To change the floor of an existing service, raise min_capacity (or backend_min_capacity). Reserve backend.priority + 1 for the /mcp alias listener rule (module validation enforces this).

ECS services, workers, and migrations

Monitoring & Alerting

Automatic CloudWatch alarms cover: ECS CPU/memory, RDS, Redis, ALB latency/unhealthy targets/5XX, and VPC flow logs. enable_cloudwatch_metric_stream (default false) sends that alarm set, plus the baseline health metrics, to the Runlayer observability Firehose endpoint. Leave it off until Runlayer has stored this account’s OTLP ingest token in Secrets Manager at runlayer/cwmetrics-firehose-api-key ({"api_key":"<bare token>"}). Firehose reads that secret. Its role may decrypt only that secret, and only through Secrets Manager, which covers both the AWS managed key and a customer managed key. A customer managed key’s policy still has to allow the Firehose role. The module does not change the key. The metrics carry this account’s name, read with account:GetAccountInformation, as the cloud_account_name label. The module creates at most one stream per account per region; if one already exists, apply leaves it alone. With monitoring, critical alerts, the audit stream, and its consumer enabled, and the consumer running at least one task (desired_count > 0 on a fixed fleet, or autoscaling on with max_capacity > min_capacity), the <project>-<environment>-audit-log-kinesis-iterator-age-high alarm watches AWS/Kinesis SubscribeToShardEvent.MillisBehindLatest for the audit stream and registered consumer: Maximum > 5 minutes for three consecutive five-minute periods. No usable telemetry becomes INSUFFICIENT_DATA without notifications; disabling the consumer or setting a fixed fleet’s desired count to zero removes the alarm. This measures read lag only, so check shard checkpoints and database writes separately to establish processing progress and liveness. With critical_alerts_extra_sns_topic_arns configured, ECS deployment failures and rollout warnings also notify those topics through CloudWatch alarms on the matching EventBridge rules. Each alarm evaluates one-minute windows and groups failures while it remains in ALARM. The local critical alerts topic continues receiving the original ECS events. Confirm delivery in your chat channel after applying; configuring an SNS destination alone does not prove that chat notifications arrive.
Database lock alarms and dashboards select metrics by Environment and CustomerId, so deployments sharing an AWS account stay separate. The db_idle_in_txn_max_duration_threshold is the idle-age boundary shared by both idle-transaction alarms (default 30 seconds). The duration alarm triggers when one session crosses it; the count alarm triggers when more than db_idle_in_txn_count_threshold sessions cross it (default 10 sessions). Both measure time since the session became idle, rather than total transaction age. Raw idle-session counts remain available on dashboards.

Resource tags

The additional_tags input accepts a string map and defaults to {}. It applies deployment metadata to directly managed workload resources. Resource identity tags take precedence. No partner attribution is enabled by default. Verify product code, resource eligibility and existing tag ownership before opt-in. See the module README for the coverage available in your published module version.

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) and reads one that Runlayer creates, the provisioned tenant secret: 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.
  • The WorkOS, Sentry and Resend keys never pass through Terraform inputs or state: Runlayer creates and fills the restricted/ provisioned tenant secret in your account and tasks read it directly. A plan fails until it exists, so have Runlayer provision it before your first apply. Every version carries all six keys (AUTH_API_KEY, RESEND_API_KEY, SENTRY_DSN, SENTRY_RELAY_PUBLIC_KEY, SENTRY_RELAY_SECRET_KEY, SENTRY_RELAY_ID; empty when unused). If an earlier module version took the WorkOS key as the auth_api_key input, copies of it remain in older state versions and your CI secret store: rotate it with Runlayer and delete the old CI secret.
  • tenant_secret_source is deprecated: it accepts only "provisioned" (the default) and goes away in the next major, so remove it from the module call.
  • tenant_key_vault_enabled = true makes your tasks read every key Runlayer issues from Runlayer’s tenant key vault, cross-account, when they start. Each key is a secret of its own there, named after your task execution role and the key, so the module finds them by itself: no ARN or key passes between you and Runlayer, and only the secrets’ ARNs are in your Terraform. The vault lets your task execution role, and nothing else, read them. It requires distribution_reader_key_source = "provisioned" and openfeature_provider = "flagd", so Runlayer can turn the key-set status check on for your deployment. The secrets expire together (7 days by default) and Runlayer renews them: a task that starts after the expiry cannot start until then, so ask Runlayer to renew before a deploy if yours are less frequent than that. ECS Terraform deployments only; the Helm chart and the operator have no equivalent yet. Ask Runlayer to onboard your deployment, and set the switch once Runlayer confirms: tasks cannot start before the secrets exist. If you pass distribution_api_key today, leave it (and mcp_catalog_api_key) set on the apply that turns the switch on, so a rollback to your previous task definition still finds the key, and remove them in a later apply once the new tasks are healthy.
  • AI Watch policy snapshot signing takes ai_watch_snapshot_signing_key and ai_watch_snapshot_delegations (one delegation per organization, public, not a secret). Get both from Runlayer; see Runlayer-provided inputs. Each delegation expires within 90 days, so renew it before then. Changing either input rolls backend-service.
  • Rotate DISTRIBUTION_API_KEY through the Terraform input and coordinate registration with Runlayer; follow the Distribution key rotation procedure so the new key is accepted before tasks use it.
  • After deploy, rotate other 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.
The deployment guide exports ecs_cluster_name. To inspect secret names with Terraform, also add these root outputs:
Apply the output-only change, then inspect names with terraform output -raw app_secrets_name or terraform output -raw restricted_app_keys_secret_name. These outputs contain names, not secret values. Use your approved secret-management workflow to update non-key values. Preserve all other keys in the JSON secret. Restart every service that consumes the changed value; for the core services:
Also restart any enabled optional consumers using that secret, then repeat the deployment verification.

Module outputs (attributes)

These are child-module attributes. terraform output reads only outputs declared in your root configuration; export an attribute there before using it from the CLI. Useful attributes include:

Common use cases

Private enterprise deployment

High availability production

Tunnel endpoint autoscaling

For managed tunnel connections, tunnel_endpoint_max_capacity greater than tunnel_endpoint_min_capacity enables automatic scale-out at 80% average reserved TCP stream capacity. Both default to 1; equal bounds pin capacity. Scale-out has a 300-second cooldown in each direction. Each endpoint defaults to 256 pending/active streams shared across its connector sessions, so the target is about 205 streams per endpoint. Scale-down retires idle endpoints. Pending and active TCP streams hold renewable ECS task protection until they finish naturally; a busy endpoint can remain above the desired task count indefinitely. Protection is released after 30 continuously idle seconds, making that task eligible for ECS scale-in. The tunnel application exports OpenTelemetry metrics to a shared private collector, which publishes the CloudWatch scaling metrics through its logs. The collector runs whenever tunnels run, even when central observability is off. It starts with one 0.25-vCPU / 512-MiB task and automatically scales on native ECS average CPU at tunnel_otel_collector_cpu_target (default 60 percent). tunnel_otel_collector_desired_count sets the initial count and runtime minimum. tunnel_otel_collector_max_capacity defaults to the larger of 4 and that minimum. Set both counts equal for fixed capacity. Scale-out has a 60-second cooldown; scale-in has a 300-second cooldown. Terraform preserves the live scaled-out count across unrelated applies. Queue depth and memory remain diagnostic signals. Central forwarding remains opt-in. Missing collector data pauses stream-based scale-out rather than reporting zero utilization; existing streams continue. Before activating autoscaling, apply installation IAM and collector changes, then deploy the revised worker/template before selecting the compatible tunnel bundle. Existing ranged services activate scaling when reconciled. Managed endpoints require the ECS agent and task-protection permissions; startup fails if protection cannot be confirmed. Workers hosted outside the module’s shared ECS task role also need ecs:DescribeTasks and ecs:UpdateTaskProtection on arn:aws:ecs:<region>:<account>:task/<endpoint-cluster>/* for upgrade observation. They also need ecs:ListTasks on *, restricted by an ArnEquals condition matching ecs:cluster to the endpoint cluster ARN. Upgrades retain their bounded drain: the worker removes old-task protection only after healthy replacements reach the current desired count, then ECS shutdown allows streams 90 seconds to finish. Automatic scale-down does not use that deadline. To stop automatic scaling without shrinking, set both bounds to the current steady running count, outside an active deployment.

Development environment