Skip to content

Auto-generated

This page is generated by terraform-docs at build time from the infra/ repo. Do not edit manually.

DSAR API (dsar-api)

ECS service for the DSAR product's API (cookiehub-com/dsar, api/: Hono + Drizzle, Node), IS-181. Follows the admin-portal / core-api service shape: own ECR repository, bridge-mode EC2 task with dynamic port mapping, target group on traffic-port, SSM-backed configuration read by the execution role at boot.

Reachable on the shared API hostname

A listener rule on the public HTTPS listener forwards hostname (the shared API hostname, api.<env>.cookiehub.net) AND path_pattern (/dsar/*) to the target group. The Route 53 record for the hostname is owned by the environment root, not this module, because core-api joins the same hostname later. The service authenticates callers itself (core-api session introspection), so there is no authenticate-oidc action. The rule and the service's load_balancer block share the flag attach_to_load_balancer, and the service depends_on the rule because ECS refuses to create a service whose target group is not yet behind a listener. What stays out of this module is the public-path routing on the dash hostname (/api/v1/dsar/*, /dsar/form/*), which arrives with the flip (CH-1215).

Optional private path

Setting internal_hostname adds a second target group, a host-only rule on the internal ALB's HTTPS listener and an alias record in the internal zone, so callers inside the VPC (the dashboard BFF) reach dsar-api without leaving it. It needs internal_https_listener_arn, internal_zone_id, internal_alb_dns_name and internal_alb_zone_id (checked by a precondition on the rule); internal_listener_rule_priority is optional. Left null, none of it is created.

Configuration

Plain settings (URLs, trusted proxies, NODE_ENV, PORT, the vault bucket and its region) are container environment values owned by Terraform. Everything hand-set is an SSM parameter under /core/<env>/dsar-api/<ENV_NAME> injected through secrets (valueFrom), read by the execution role at task start:

  • SecureString credentials: created with a placeholder, real values set by hand after apply, ignore_changes = [value].
  • Mail (MAIL_HOST/PORT/SECURE/USERNAME/PASSWORD): created and injected only when wire_mail_parameters is true. Set the real values first.
  • Optional (DSAR_OK_COMPLAINT_URL, LOG_LEVEL): created as placeholders but NOT injected until wire_optional_parameters is true, because the app would treat a placeholder string as a real value.

Task role

Read/write/delete on the DSAR vault bucket, as a standalone aws_iam_role_policy (never inline_policy, so other policies can be added to the role later). Egress to customers' own buckets is a network matter (443 out on the core ECS security group), not IAM.

Deploys vs. Terraform

Application deploys register new task-definition revisions (new image tag) and update the service; Terraform owns the task shape. The service tracks the newest ACTIVE revision of the family, so a deploy is never rolled back by an apply. The OIDC deploy role is a separate change (IS-180).

Requirements

Name Version
terraform >= 1.6.0
aws ~> 6.0

Providers

Name Version
aws ~> 6.0

Modules

No modules.

Resources

Name Type
aws_cloudwatch_log_group.dsar_api resource
aws_ecr_lifecycle_policy.dsar_api resource
aws_ecr_repository.dsar_api resource
aws_ecs_service.dsar_api resource
aws_ecs_task_definition.dsar_api resource
aws_iam_policy.read_ssm resource
aws_iam_role.execution_role resource
aws_iam_role.scheduler resource
aws_iam_role.task_role resource
aws_iam_role_policy.dsar_vault resource
aws_iam_role_policy.scheduler_run_task resource
aws_iam_role_policy_attachment.execution_read_ssm resource
aws_iam_role_policy_attachment.execution_role_policy resource
aws_lb_listener_rule.dsar_api resource
aws_lb_listener_rule.dsar_api_internal resource
aws_lb_target_group.dsar_api resource
aws_lb_target_group.dsar_api_internal resource
aws_route53_record.dsar_api_internal resource
aws_scheduler_schedule.job resource
aws_scheduler_schedule_group.dsar_jobs resource
aws_ssm_parameter.mail_secret resource
aws_ssm_parameter.mail_string resource
aws_ssm_parameter.optional resource
aws_ssm_parameter.secret resource
aws_caller_identity.current data source
aws_ecs_task_definition.dsar_api data source
aws_iam_policy_document.ecs_assume_role data source
aws_iam_policy_document.scheduler_assume_role data source

Inputs

Name Description Type Default Required
alb_https_listener_arn ARN of the public ALB HTTPS listener the listener rule is attached to string n/a yes
attach_to_load_balancer Create the listener rule and register the service with the target group. The rule and the registration go together: ECS rejects a service whose target group is not behind a listener rule. bool true no
base_tags Base tags applied to all resources map(string) n/a yes
cluster_name ECS cluster name to deploy the service into (the core cluster) string n/a yes
container_port Port the container listens on number 3000 no
core_api_url Base URL of core-api that dsar-api calls (CORE_API_URL) string n/a yes
dash_allowed_origins Browser origins allowed to call dsar-api (DASH_ALLOWED_ORIGINS, comma separated) string n/a yes
dash_url Public URL of the dashboard (DASH_URL) string n/a yes
deployment_maximum_percent ECS rolling-deploy maximum percent number 200 no
deployment_minimum_healthy_percent ECS rolling-deploy minimum healthy percent number 100 no
desired_count Desired number of ECS tasks. 0 keeps the service defined with nothing running. number 1 no
environment Environment name (used in the SSM parameter path /core//dsar-api/*) string n/a yes
health_check_path ALB health-check path string "/health" no
hostname Shared API hostname the rule matches (e.g. 'api.stage.cookiehub.net'). Its DNS record lives in the environment root. Must be covered by a certificate already on the HTTPS listener; this module attaches none. string n/a yes
image_tag ECR image tag Terraform's task-definition revision references. Deploys register their own revisions and the service follows the newest one, so this only matters for the first deploy and for revisions Terraform registers after a task change. string "latest" no
internal_alb_dns_name DNS name of the internal ALB (alias target). Required when internal_hostname is set. string null no
internal_alb_zone_id Hosted zone ID of the internal ALB (alias target). Required when internal_hostname is set. string null no
internal_hostname Hostname for dsar-api's private path on the internal ALB (e.g. 'dsar-api.internal.stage.cookiehub.net'). Null leaves the private path off: no second target group, rule or record is created. string null no
internal_https_listener_arn ARN of the internal ALB HTTPS listener. Required when internal_hostname is set. string null no
internal_listener_rule_priority Explicit priority of the host-header rule on the internal listener. Null lets the provider pick the next free one. number null no
internal_zone_id Route53 zone ID of the internal zone holding internal_hostname. Required when internal_hostname is set. string null no
jobs_command Container command per scheduled job (the contract with the dsar-api jobs entrypoint) map(list(string))
{
"cleanup": [
"node",
"dist/jobs.js",
"cleanup"
],
"remind": [
"node",
"dist/jobs.js",
"remind"
]
}
no
jobs_enabled Enable the remind and cleanup schedules. Schedules are created DISABLED; enable after the dsar-api jobs entrypoint is deployed. RunTask ignores desired_count, so enabling starts tasks even while the service runs at 0. bool false no
listener_rule_priority Priority of the listener rule on the public HTTPS listener. Required: it must be unused on the listener, and the host+path rule has to sit before any broader rule on the same hostname. number n/a yes
log_retention_days CloudWatch Logs retention for the task's log group number 30 no
name_prefix Prefix for resource names (e.g. 'stage-euc1-core') string n/a yes
path_pattern Path pattern the rule matches together with the hostname string "/dsar/*" no
region AWS region string n/a yes
task_cpu CPU units for the ECS task number 512 no
task_memory Memory in MB for the ECS task (hard limit) number 512 no
trusted_proxies Proxy addresses/CIDRs trusted for X-Forwarded-* (TRUSTED_PROXIES, comma separated). Mirrors core-api's value in the same environment. string n/a yes
vault_bucket_name Name of the DSAR vault S3 bucket the task role may list, read, write and delete in (also injected as DSAR_VAULT_BUCKET) string n/a yes
vault_bucket_region Region the DSAR vault bucket is in (DSAR_VAULT_REGION). The app falls back to us-east-1 when unset. string n/a yes
vpc_id VPC ID (used for the ALB target group) string n/a yes
wire_mail_parameters Create the MAIL_* SSM parameters and inject them into the task. Leave false where there is no SMTP (stage). Turn on only once the real values can be set: placeholders in MAIL_PORT / MAIL_SECURE fail the app's config parsing at boot. bool false no
wire_optional_parameters Inject the optional parameters (DSAR_OK_COMPLAINT_URL, LOG_LEVEL) into the task. Leave false until their real values are set: the app would treat the placeholder as a real value. bool false no

Outputs

Name Description
cluster_name Name of the ECS cluster the service runs in
ecr_repository_arn ARN of the dsar-api ECR repository (for the deploy role's push grant)
ecr_repository_url URL of the dsar-api ECR repository
execution_role_arn ARN of the ECS task execution role (needed by the deploy role's iam:PassRole)
hostname Shared API hostname the listener rule matches
job_schedule_arns ARNs of the scheduled job schedules, keyed by job (remind, cleanup)
log_group_name CloudWatch log group name
scheduler_role_arn ARN of the EventBridge Scheduler execution role
service_arn ARN of the ECS service
service_name ECS service name (for monitoring alarms and the deploy workflow)
ssm_parameter_names All SSM parameter names, keyed by environment variable name. SecureStrings and placeholders need real values set out of band.
target_group_arn ARN of the ALB target group (the host+path rule forwards here; CH-1215's dash path rules forward here too)
target_group_arn_suffix ARN suffix of the ALB target group (TargetGroup CloudWatch dimension), for monitoring alarms
task_definition_arn ARN of the task definition revision Terraform registered. For a RunTask schedule use the family or arn_without_revision so it follows deploys.
task_definition_arn_without_revision Task definition ARN without the revision, resolves to the latest ACTIVE revision (for RunTask schedules)
task_definition_family Task definition family (e.g. prod-euc1-core-dsar-api)
task_role_arn ARN of the ECS task role (the container's AWS identity)
task_role_name Name of the ECS task role, for attaching further aws_iam_role_policy resources