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
<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)?- CIDR Block Association naming - currently has no
Nametag in the module. Confirming HCA wants one added, or if it should remain untagged. - 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.
- Tag vs. resource-name argument - this pattern is proposed for both the
Nametag (most resources) and the literalnameargument (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.