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_parametersis true. Set the real values first. - Optional (DSAR_OK_COMPLAINT_URL, LOG_LEVEL): created as placeholders but
NOT injected until
wire_optional_parametersis 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¶
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/ |
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)) |
{ |
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 |