# Resource Naming Convention

All Terraform-provisioned resources that support a name attribute SHALL follow this pattern:

```hcl
${var.prefix}-${var.region}-<name>-${var.env}
```

Where:

- **prefix** - Set in `terraform.tfvars` (e.g. `wikijs`). Used for Parameter Store paths and resource naming.
- **region** - AWS region (e.g. `us-east-1`, `eu-west-1`).
- **&lt;name&gt;** - A short identifier for the resource, set **per resource** in `terraform.tfvars`. Each layer defines one or more variables for the `<name>` part (e.g. `tfstate_name`, `dns_assume_role_name`, `vpc_name`, `alb_sg_name`).
- **env** - Deployment environment (e.g. `dev`, `prod`, `sandbox`).

Example: with `prefix = "wikijs"`, `region = "us-east-1"`, `env = "dev"`, and `dns_assume_role_name = "dns"`, the DNS IAM role name is `wikijs-us-east-1-dns-dev`.

## Why this convention

- **Consistency** - Same pattern across all layers and resource types.
- **Configurability** - The `<name>` part is defined in `terraform.tfvars` per resource, so names can be changed per environment or deployment without editing code.
- **Traceability** - Prefix, region, and env in every name make it clear which project, region, and environment a resource belongs to.

## Per-layer name variables

Each layer declares variables for the `<name>` part of the resources it creates. Set these in `terraform.tfvars`.

| Layer | Name variables (examples) | Used for |
| ------- | --------------------------- | ---------- |
| **00-bootstrap** | `tfstate_name`, `secrets_key_name` | KMS keys/aliases, state bucket name |
| **01-dns-main** | `dns_assume_role_name` | DNS IAM role |
| **10-network** | `vpc_name`, `ngw_name`, `igw_name`, `route_table_name`, `eks_cluster_name`, `alb_sg_name`, `workload_sg_name`, `rds_sg_name`, `endpoint_sg_name`, `s3_gateway_name`, `sts_endpoint_name`, `ssm_endpoint_name`, `secretsmanager_endpoint_name`, `ecr_api_name`, `ecr_dkr_name`, `logs_endpoint_name` | VPC, NAT/IGW, route table, security groups, VPC endpoints |
| **20-eks** | `cluster_name_suffix` | EKS cluster name (when `cluster_name` is null) |
| **30-data-rds** | `rds_instance_name` | RDS instance identifier (when `identifier` is null) |
| **35-storage-s3-assets** | `assets_bucket_name`, `kms_assets_name`, `irsa_role_name`, `irsa_policy_name` | S3 bucket, KMS alias, IRSA role and policy |
| **40-platform** | `ebs_storage_class_name` | EBS StorageClass name |
| **45-argocd** | (none; uses Helm/namespace names) | - |
| **50-app-wikijs** | `app_secret_name`, `alb_name_suffix` | Wiki.js app secret, ALB name for lookup (max 32 chars) |

## Special cases

- **S3 bucket (00-bootstrap state)** - Single-account deployment; name follows the standard pattern: `${var.prefix}-${var.region}-${var.tfstate_name}-${var.env}`.
- **S3 assets bucket (35)** - Same pattern; bucket name includes `account_id` for global S3 uniqueness across accounts if the same prefix/region/env is used elsewhere.
- **ALB name (50-app-wikijs)** - Truncated to 32 characters for AWS. The same value must be used in `apps/wikijs/values/<env>.yaml` as `alb.ingress.kubernetes.io/load-balancer-name` so Terraform can look up the ALB after the ingress is created.
- **Parameter Store paths** - Unchanged: `/<prefix>/<region>/<env>/<layer>/<key>` (paths are not resource names).

## Ensuring names are passed through

1. **Define the variable** in the layer's `variables.tf` with a description that states it is the `<name>` part of the convention.
2. **Use it in `main.tf`** (or equivalent) as `${var.prefix}-${var.region}-${var.<name_var>}-${var.env}` (or with `local` where needed).
3. **Set it in `terraform.tfvars`** for the layer so the chosen name is explicit per environment.
4. **Set and document in `terraform.tfvars`** so the chosen name is explicit per environment; optional variables can use defaults in `variables.tf`.

Cross-layer references (e.g. EKS cluster name from 10-network and 20-eks) must use the same formula and matching name variables (e.g. `eks_cluster_name` in 10-network and `cluster_name_suffix` in 20-eks both default to `"eks"`) so subnet tags and cluster name align.