# Naming Convention Proposal for the VPC Module

Pattern base: `<org>-<env>-<tier>-<region_abbr>-<resource-type>[-<zone_id>][-<idx>]`

## Naming Table

| Resource                       | Naming Pattern                                                     | Example                                   |
| ------------------------------ | ------------------------------------------------------------------ | ----------------------------------------- |
| VPC                            | `<org>-<env>-<tier>-<region_abbr>-vpc`                             | `hca-dev-dmz-usw2-vpc`                    |
| CIDR Block Association         | `<org>-<env>-<tier>-<region_abbr>-vpc-cidr`                        | `hca-dev-dmz-usw2-vpc-cidr`               |
| Subnet (Public)                | `<org>-<env>-<tier>-<region_abbr>-subnet-public-<zone_id>-<idx>`   | `hca-dev-dmz-usw2-subnet-public-az1-01`   |
| Subnet (Private)               | `<org>-<env>-<tier>-<region_abbr>-subnet-private-<zone_id>-<idx>`  | `hca-dev-dmz-usw2-subnet-private-az1-01`  |
| Subnet (Isolated)              | `<org>-<env>-<tier>-<region_abbr>-subnet-isolated-<zone_id>-<idx>` | `hca-dev-dmz-usw2-subnet-isolated-az2-01` |
| Internet Gateway               | `<org>-<env>-<tier>-<region_abbr>-igw`                             | `hca-dev-dmz-usw2-igw`                    |
| NAT Gateway EIP                | `<org>-<env>-<tier>-<region_abbr>-nat-eip-<zone_id>-<idx>`         | `hca-dev-dmz-usw2-nat-eip-az1-01`         |
| NAT Gateway                    | `<org>-<env>-<tier>-<region_abbr>-nat-<zone_id>-<idx>`             | `hca-dev-dmz-usw2-nat-az1-01`             |
| Route Table (Public)           | `<org>-<env>-<tier>-<region_abbr>-rt-public`                       | `hca-dev-dmz-usw2-rt-public`              |
| Route Table (Private)          | `<org>-<env>-<tier>-<region_abbr>-rt-private-<zone_id>-<idx>`      | `hca-dev-dmz-usw2-rt-private-az1-01`      |
| Route Table (Isolated)         | `<org>-<env>-<tier>-<region_abbr>-rt-isolated-<zone_id>-<idx>`     | `hca-dev-dmz-usw2-rt-isolated-az2-01`     |
| Transit Gateway VPC Attachment | `<org>-<env>-<tier>-<region_abbr>-tgw-attach`                      | `hca-dev-dmz-usw2-tgw-attach`             |
| Flow Log IAM Role              | `<org>-<env>-<tier>-<region_abbr>-flow-log-role`                   | `hca-dev-dmz-usw2-flow-log-role`          |
| Flow Log IAM Role Policy       | `<org>-<env>-<tier>-<region_abbr>-flow-log-policy`                 | `hca-dev-dmz-usw2-flow-log-policy`        |
| VPC Flow Log                   | `<org>-<env>-<tier>-<region_abbr>-flow-log`                        | `hca-dev-dmz-usw2-flow-log`               |

## Token Definitions

| Token           | Source                                                     | Notes                                                                                                                                                                           |
| --------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<org>`         | Caller-supplied input                                      | No module-side assumption; explicit every time                                                                                                                                  |
| `<env>`         | Caller-supplied input                                      | Validated against approved list (prod, staging, dev, sandbox, shared-services-prod, shared-services-nonprod, log, backup)                                                       |
| `<tier>`        | Caller-supplied input                                      | Optional — omitted cleanly (via `compact()`) when not applicable, e.g. `hca-log-usw2-vpc`                                                                                       |
| `<region_abbr>` | Derived — parsed from `aws_availability_zones.zone_ids[0]` | e.g. `usw2-az1` -> `usw2`. No hardcoded region map; sourced directly from AWS-returned data                                                                                     |
| `<zone_id>`     | Derived per-subnet, from `zone_ids` (e.g. `az1`, `az2`)    | Not the AZ name letter (`a`, `b`) - the letter is randomized per AWS account and is not consistent across a multi-account estate. `zone_id` is the physically stable identifier |
| `<idx>`         | To be defined - TBD with HCA                               | Disambiguates multiple subnets/resources within the same AZ. Semantics (sequential vs. caller-fixed) need confirmation                                                          |

## Scope Notes

- **Region-scoped resources** (no `<zone_id>` in pattern): VPC, CIDR association, Internet Gateway, public Route Table, TGW Attachment, IAM role/policy, VPC Flow Log - these are not bound to a specific AZ.
- **AZ-scoped resources** (`<zone_id>` required): Subnets, NAT Gateway, NAT EIP, private/isolated Route Tables - each instance lives in exactly one AZ.

## Open Questions for HCA

1. **`<idx>` semantics** - should this represent a sequential count of subnets created within an AZ, or a caller-fixed number tied to a specific CIDR block (stable even if other subnets are added/removed later)?
2. **CIDR Block Association naming** - currently has no `Name` tag in the module. Confirming HCA wants one added, or if it should remain untagged.
3. **Case/separator convention** - proposing all-lowercase, hyphen-separated, no underscores, to align with AWS-side naming restrictions (S3, IAM, etc.). Confirming this as a hard rule.
4. **Tag vs. resource-name argument** - this pattern is proposed for both the `Name` tag (most resources) and the literal `name` argument (IAM role, IAM role policy) where applicable. Confirming HCA is fine applying one convention to both.

## Length Constraint Analysis

AWS enforces hard character limits on certain resource name arguments (not tags):

| Resource                       | AWS Limit | Type           |
| ------------------------------ | --------- | -------------- |
| IAM Role `name`                | 64 chars  | Hard API limit |
| IAM Role Policy `name`         | 128 chars | Hard API limit |
| Tag values (`Name` and others) | 256 chars | Hard API limit |

Worst-case stress test using the longest approved `env` value (`shared-services-nonprod`, 24 chars):

`hca-shared-services-nonprod-dmz-usw2-flow-log-role` ~= 52 chars - within the 64-char IAM role limit today, but leaves limited headroom if `org` or `tier` inputs grow longer.

**Mitigation:** the module will validate assembled name length against the tightest applicable limit (IAM role names, 64 chars) via a `lifecycle.precondition` on the affected resources, failing at plan/apply time with a clear error message rather than an opaque AWS API rejection. This validates the caller-supplied prefix combination, not just individual inputs in isolation, since it's the concatenated result that determines whether the limit is breached.