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):
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: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.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 whenexternal_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 fullservices_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
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.
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
Theadditional_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_KEYandMASTER_SALTare 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 theauth_api_keyinput, 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_sourceis 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 = truemakes 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 requiresdistribution_reader_key_source = "provisioned"andopenfeature_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 passdistribution_api_keytoday, leave it (andmcp_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_keyandai_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 rollsbackend-service. - Rotate
DISTRIBUTION_API_KEYthrough 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_SALTviasecret_key/master_saltinstead — Terraform reverts out-of-band edits to the restricted secret on the next apply.
ecs_cluster_name. To inspect secret names with Terraform, also add these root outputs:
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:
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.