Auto-generated
This page is generated by terraform-docs at build time from the infra/ repo. Do not edit manually.
Core API¶
ECS service for the CookieHub Core API. Includes its own ECR repository, deployed behind the public ALB with environment-specific hostname and TLS certificate. Handles consent management and client-facing API endpoints.
Optional private path¶
Setting internal_hostname adds a second target group, a host-header rule on
the internal ALB's HTTPS listener and an alias record in the internal zone, so
callers inside the VPC (the dashboard BFF, dsar-api) reach core-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.
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_dns_name | DNS name of the public ALB (for Route53 alias target) | string |
n/a | yes |
| alb_https_listener_arn | ARN of the public ALB HTTPS listener | string |
n/a | yes |
| alb_security_group_id | Security group ID of the public ALB | string |
n/a | yes |
| alb_zone_id | Canonical hosted zone ID of the public ALB (for Route53 alias) | string |
n/a | yes |
| atrax_api | Base URL of the Atrax crawler API (e.g. 'https://atrax-api.stage.cookiehub.net'). Empty disables the integration — scan endpoints refuse and scan-detail URLs come back empty. | string |
"" |
no |
| auth_cookie_domain | Domain attribute on core-api's session cookies. Must EXACTLY match what the environment's Laravel sets for chtoken or sessions fork between the two dashboards. Empty (host-only) matches stage, where Laravel has no SESSION_DOMAIN; prod sets '.cookiehub.com'. | string |
"" |
no |
| base_tags | Base tags to apply to all resources | map(string) |
{} |
no |
| borgun_3ds_term_url | BORGUN_3DS_TERM_URL, the 3DS TermURL base the pending-payment id is appended to. Empty leaves it out. | string |
"" |
no |
| borgun_enabled | Create the Borgun/Teya gateway key SSM parameters and inject them into the task (CH-867). Off by default: only stage opts in until the charge leg is reviewed for production. |
bool |
false |
no |
| borgun_transaction_type | BORGUN_TRANSACTION_TYPE sent as TransactionType on every payment. Empty leaves it out. | string |
"" |
no |
| borgun_url | BORGUN_URL, the RPG API base URL (sandbox or production host). Empty leaves it out of the task environment. | string |
"" |
no |
| cdn_bucket | Public CDN bucket core-api writes per-domain widget artifacts to on publish (c2/{code}.js, c2/css/{code}.css, client/{code}/.json), and reseller logos to (reseller-logos/, CH-251). Environment-specific: stage is cookiehub-stage-cdn, prod is cookiehub-cdn. The widget-artifact write grant is deliberately NOT declared here: on stage it is a manual inline policy on the task role (cdn-artifacts-write) and on prod the cookiehub-cdn bucket policy (IS-2, imported by IS-65). The reseller-logo grant IS declared here (reseller_logos_write, PutObject on reseller-logos/ only). Empty leaves CDN_BUCKET out of the task environment and drops that grant. |
string |
"" |
no |
| cdn_default | Base URL of the default (shared Bunny) CDN zone (cdn_id 2 domains), embedded by the compiler INTO the emitted widget. Same failure mode and treatment as cdn_legacy. |
string |
"" |
no |
| cdn_development | Base URL for dev-environment widget artifacts. Deliberately unset until CH-241 decides the dev/preview artifact destination — nothing compiles the dev environment through core-api yet. |
string |
"" |
no |
| cdn_legacy | Base URL of the legacy CDN zone (cdn_id 0/1 domains), embedded by the compiler INTO the emitted widget — a wrong value ships a broken loader rather than failing loudly, which is why it has no default. Empty leaves CDN_LEGACY out of the task environment and the publish endpoint answers 503. |
string |
"" |
no |
| cdn_preview | Base URL for preview-environment widget artifacts. Deliberately unset until CH-241 — see cdn_development. |
string |
"" |
no |
| certificate_arn | ARN of the ACM certificate for the hostname | string |
n/a | yes |
| cluster_name | ECS cluster name to deploy the service into | string |
n/a | yes |
| container_port | Port the container listens on | number |
3000 |
no |
| core_app_url | Public URL of the legacy Laravel dashboard (e.g. 'https://dash.stage.cookiehub.net') — NOT core-api's own hostname. Atrax posts scan results to /checker/callback and /implementation/callback on this host; a wrong value means scans run but results are never recorded. Empty leaves CORE_APP_URL out of the task environment and scan requests are refused. | string |
"" |
no |
| create_oidc_provider | Whether to create the GitHub Actions OIDC provider. True for stage (creates it); false for prod (an account-wide provider already exists and is referenced via data source). | bool |
true |
no |
| dash_allowed_origins | Comma-separated origins allowed to make credentialed requests to /dash/v1 — the React dashboard's origin(s) (e.g. 'https://dash-next.stage.cookiehub.net'). Empty means only same-origin callers pass. | string |
"" |
no |
| dash_api_enabled | Mount core-api's dashboard surface (/dash/v1) for the React dashboard (CH-323). 'true'/'false'; empty string leaves core-api's own default (off), so existing deployments are unaffected until an environment opts in. | string |
"" |
no |
| dash_url | Absolute base URL of the dashboard the tokenized links in core-api's mails point at (signup verification, magic link, password reset, welcome). This is the dashboard core-api itself backs — on stage during the dual-run that is the React dashboard's own hostname, not Laravel's. Empty leaves DASH_URL out of the task environment, and core-api falls back to its production default (https://dash.cookiehub.com), which is wrong for every other environment. |
string |
"" |
no |
| deployment_maximum_percent | ECS rolling-deploy maximum percent. Default 200. Pair with minimum_healthy_percent=0 and set to 100 for stop-before-start on capacity-constrained instances. | number |
200 |
no |
| deployment_minimum_healthy_percent | ECS rolling-deploy minimum healthy percent. Default 100 (zero-downtime start-before-stop). Set to 0 where the cluster instance can't fit a second task alongside co-tenants (e.g. prod core shares a t3.small with atrax-api), allowing stop-before-start. | number |
100 |
no |
| desired_count | Desired number of ECS tasks | number |
1 |
no |
| ecs_security_group_id | Security group ID of ECS tasks (ingress rule for ALB will be added to it) | string |
n/a | yes |
| environment | Environment name | string |
n/a | yes |
| extra_hostnames | Additional host-header values the public listener rule also matches (e.g. the shared API hostname 'api.stage.cookiehub.net'). Their DNS records live in the environment root and the names must be covered by a certificate already on the listener. | list(string) |
[] |
no |
| github_oidc_refs | Subject conditions for the deploy role's trust policy, each appended to repo:<org>/<repo>:. A list rather than a string because a job that declares an environment: presents environment:<name> as its subject instead of ref:<git ref>, so a role fronting a gated production deploy has to trust both forms or the assume-role fails. Stage deploys present ref:refs/heads/main (a workflow_run job always reports the default branch); prod release deploys present ref:refs/tags/v*. |
list(string) |
[ |
no |
| github_repo | GitHub repository (org/repo) allowed to deploy via OIDC | string |
"cookiehub-com/core-api" |
no |
| hostname | Public-facing hostname (e.g. 'core-api.stage.cookiehub.net' or 'api.cookiehub.com') | 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 ACTIVE 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 core-api's private path on the internal ALB (e.g. 'core-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 |
| listener_rule_priority | Explicit priority of the host-header listener rule. Null lets the provider pick the next free one. | number |
null |
no |
| mail_log_links | "true" makes core-api's suppressed-mail log line (MAIL_HOST unset) carry the links found in the mail, so a stage smoke can read a verification, magic or reset link out of CloudWatch (CH-469). Stage only: the links are credentials. Empty leaves MAIL_LOG_LINKS out of the task environment. |
string |
"" |
no |
| name_prefix | Prefix for resource names | string |
n/a | yes |
| rds_security_group_id | Security group ID of the MariaDB RDS instance (ingress rule for ECS will be added). Empty string skips the ingress rule, for a root that wires database connectivity itself. | string |
"" |
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 | number |
512 |
no |
| trusted_proxies | Comma-separated IPs/CIDRs of our own forwarding hops (VPC CIDR for the ALB nodes and BFF tasks, plus the NAT gateway EIP — the BFF reaches core-api via the public ALB through NAT, so the second ALB records the NAT EIP as its client). core-api resolves the real client as the first X-Forwarded-For entry from the right not in this list. Empty keeps rightmost-entry resolution. | string |
"" |
no |
| vault_api_url | Base URL of the vault-api service for consent analytics (e.g. 'https://vault-api.internal.stage.cookiehub.net'). Empty disables the integration — vault-backed endpoints return 503. | string |
"" |
no |
| vpc_id | VPC ID (used for the ALB target group) | string |
n/a | yes |
| widget_releases_bucket | S3 bucket holding the widget build artifacts core-api reads at publish time. Environment-specific: stage publishes to cookiehub-stage-release, prod to cookiehub-release (which predates the cookiehub- Empty disables the grant and leaves WIDGET_RELEASES_BUCKET out of the task environment. |
string |
"" |
no |
| widget_version | Fallback widget version string, used only when a domain's widget_versions row carries no version. Mirrors Laravel's WIDGET_VERSION env value. |
string |
"" |
no |
| zone_id | Route53 hosted zone ID | string |
n/a | yes |
Outputs¶
| Name | Description |
|---|---|
| container_name | Name of the core-api container in the task definition |
| ecr_repository_url | ECR repository URL for core-api |
| execution_role_arn | ARN of the core-api task execution role |
| log_group_name | CloudWatch log group of the core-api container (stream prefix ecs) |
| target_group_arn | ARN of the ALB target group |
| target_group_arn_suffix | ARN suffix of the ALB target group (TargetGroup CloudWatch dimension), for monitoring alarms |
| task_definition_family | Task definition family of core-api; scheduled jobs run it without a revision (newest ACTIVE) |
| task_role_arn | ARN of the core-api task role |