feat(ec2): add subnetNameTagStrategy to tag subnets after their AZ

[jkodroff]

Fixes #913.

Subnets are currently tagged after the 1-based index of their AZ — vpc-public-1, vpc-public-2, vpc-public-3. Naming them after the AZ itself is more useful when you're reading the console. This adds an opt-in way to do that.

const vpc = new awsx.ec2.Vpc("vpc", {
  numberOfAvailabilityZones: 3,
  subnetNameTagStrategy: "AvailabilityZone",   // new; defaults to "Legacy"
});

subnetNameTagStrategy	subnet Name tags
Legacy (default)	vpc-public-1, vpc-public-2, vpc-public-3
AvailabilityZone	vpc-public-1a, vpc-public-1b, vpc-public-1c

Why this shape

This only changes the AWS Name tag. Pulumi logical resource names and URNs are untouched.

That's the whole design constraint. A child's Pulumi resource name is its identity: the generated name is the logical name for the subnet and for the route table, route table association and routes hanging off it. Changing it would change four URNs per subnet, so Pulumi would delete and recreate every subnet in every existing VPC — which in practice doesn't even complete, because the delete fails while ENIs are attached. Tagging is an in-place update instead, and it's reversible.

Concretely, every spec carries two names:

• resourceName — the index-based name (vpc-public-1). Always used as the Pulumi resource name for the subnet and its route table, association and routes, under either strategy.
• nameTag — the strategy-dependent AWS Name tag. The only thing subnetNameTagStrategy affects.

Because no resource is ever renamed, no aliases are needed anywhere, and opting in (or backing out) is a tag update rather than a state migration.

It's an opt-in strategy enum defaulting to Legacy, mirroring the existing subnetStrategy, and orthogonal to it: all four allocators (Legacy, Auto, AutoMerge, Exact) honor it. That last part matters — subnetStrategy still defaults to Legacy, so a feature that only worked under Auto would be invisible to most of the install base.

Two smaller things worth calling out:

The CIDR allocation table is keyed off a name. It's deliberately pinned to the index-based form (subnetAllocationID), so the address ranges a user gets can't depend on what their subnets are tagged. There's a test asserting the allocated blocks are byte-identical under either strategy.

extractSubnetSpecInputFromLegacyLayout reads resourceName, not nameTag. It recovers a spec name by stripping a trailing index, and -1a doesn't match \d+$. Reading the resource name keeps the derived subnetLayout output identical under either strategy, with no regex change.

Anything doing tag-based subnet lookup will of course notice the new tag values — that's the point of the feature, but it's the one user-visible effect to be aware of when opting in.

AZ suffix

us-east-1a → 1a, by stripping the region prefix (/^[a-z]{2}(?:-[a-z]+)+-/) rather than pattern-matching the tail. That handles every AZ shape AWS hands out — GovCloud (us-gov-west-1a → 1a), China, the ISO partitions (us-isob-east-1b → 1b), Local Zones (us-west-2-lax-1a → 2-lax-1a) and Wavelength Zones, which end in a digit rather than a letter (us-east-1-wl1-bos-wlz-1 → 1-wl1-bos-wlz-1).

Because every AZ in a region shares that prefix exactly, stripping it preserves uniqueness — two AZs in one region can't reduce to the same suffix. A tail-matching rule would have collapsed us-west-2-lax-1a and us-west-2-den-1a both to 1a. There's a validateAzSuffixes guard for the fallback path anyway.

Tests

awsx/ec2/subnetNaming.test.ts (new) covers the suffix rule against a corpus of every AZ shape across ~25 regions and partitions, asserting name validity and per-region uniqueness for all of them, plus a fast-check property over generated AZ names.

awsx/ec2/vpc.test.ts covers the allocators (all four honor the strategy; default is unchanged; CIDR blocks and subnetLayout identical under either strategy) and the component itself under mocks: that the subnets, route tables, route table associations and routes all keep their index-based resource names under both strategies, that only the Name tags on the subnets and route tables change, that no resource gains an alias, and that NAT gateways and EIPs are untouched.

The component tests use us-west-2, so the expected suffixes are 2a/2b/2c — a bug that hardcoded 1 or dropped the region number would still have passed in us-east-1.

The validateAzSuffixes guard is covered at the component level by spying on it (called with the AZ list under AvailabilityZone, not called under the default) rather than by asserting the throw. A throw inside initialize() surfaces as an unhandled rejection out of the ComponentResource constructor that no caller can catch — it crashes the Jest worker rather than failing a test. The guard's own throw path is unit-tested in subnetNaming.test.ts.

443 tests pass; tsc and prettier clean. (yarn --cwd awsx lint fails on a pre-existing no-unused-expression in vpc.ts, unchanged from master.)

🤖 Generated with Claude Code

[eon-pulumi]

Review Verdict: Comment Only

Adds a new public schema surface (subnetNaming enum + Vpc input) generated into five language SDKs — a one-way door on the public contract, so a maintainer should own it. Implementation is clean: schema regeneration is byte-identical, Legacy remains the default with zero behavior change, and aliases correctly make opt-in a rename rather than a replace. Only two non-blocking nits found. Automated low-risk assessment, not a human review.

---

View session · Was this review helpful? Yes · No

[github-actions]

Does the PR have any schema changes?

Looking good! No breaking changes found.
No new resources/functions.

Maintainer note: consult the runbook for dealing with any breaking changes.

[eon-pulumi-agent]

Reviewed the subnetNaming addition across correctness, tests, AGENTS.md/REVIEW.md compliance, and AWS service facts.

The implementation is solid and the direction is safe: Legacy stays the default, the guard/allocator wiring threads the strategy through all four allocators, and opting in is a rename rather than a delete-and-recreate because every renamed resource (subnet, route table, association, route) carries an alias back to its index-based name. I confirmed the alias approach is sound given Pulumi URN semantics (URNs embed the parent type chain but not parent names, so each child's name-only alias resolves to the correct old URN even though its parent subnet is also renamed). The CIDR allocation key is deliberately pinned to the index-based name, so address ranges don't move when opting in, and extractSubnetSpecInputFromLegacyLayout reads legacySubnetName to keep the derived layout identical under either naming.

Verification I ran: regenerated schema.json from provider/pkg/schemagen/ec2.go — byte-identical to the committed file, so the schema and all five SDK diffs are clean regenerations, purely additive (new optional plain enum arg), not a breaking change. tsc is clean and the ec2 test suites pass (388 tests locally). The AZ-suffix regex was validated against real AZ/Local Zone/Wavelength/GovCloud/China/ISO shapes across partitions; within-region uniqueness holds by construction, and the fallback path is guarded by validateAzSuffixes.

No correctness or security defects found. Two non-blocking nits are inline. Withholding approval only because this adds a new public schema surface (subnetNaming enum + Vpc input) — a one-way door for external consumers across five language SDKs — so a maintainer should own that contract. Required CI checks were still in progress at review time (none failing); this is an automated assessment, not a human review.

[eon-pulumi-agent]

Nit — tests

The component-level wiring of this guard is untested. validateAzSuffixes has unit tests for its throw path (subnetNaming.test.ts), but no vpc.test.ts case proves that Vpc actually calls it when subnetNaming="AvailabilityZone" (and skips it under the default). A regression that dropped this call, or ran it under Legacy, would not be caught.

A single component test — e.g. new Vpc(..., { subnetNaming: "AvailabilityZone", availabilityZoneNames: ["us-east-1a", "1a"] }) expecting a throw — would close the gap.

[corymhall]

@jkodroff is your primary use case for this change visibility in the AWS console? If so then a simpler approach would be to just change the Name tag. This eliminates aliases, one-way migration behavior, state adoption risk, and downstream changes based on URNs. The change becomes reversible and AWS updates the tags in place.

[jkodroff]

Good catch. (and that's me talking, not Claude)

Not intentional to change any resource names - just the Name tag. Will fix.

[jkodroff]

Fixed.

[corymhall]

Looks good! I just have a couple of small naming updates I think we should make now that we are only updating the name tag and not the resource name.

[corymhall]

I think we should update this to something like:

Controls the AWS Name tags applied to generated subnets and their associated route tables. Pulumi logical resource names and URNs are unchanged. Optional; defaults to Legacy.

[jkodroff]

Done, used your wording nearly verbatim.

[corymhall]

I think we should update the names of these properties now. Maybe resourceName and nameTag?

[jkodroff]

Done: subnetName → nameTag and legacySubnetName → resourceName, threaded through both distributors, vpc.ts and the tests.

One knock-on worth flagging: OverlappingSubnet.subnetName also became resourceName, since specs get passed to it structurally. The index-based name is the right identifier for those overlap/gap error messages anyway, and it keeps them identical under either strategy.

[corymhall]

I think we should update this to be something like subnetNameTagStrategy to make it clear that this is only changing the name tag.

[jkodroff]

Done — renamed to subnetNameTagStrategy, and renamed the enum type to SubnetNameTagStrategy to match. Also reworded the two enum value descriptions, which still said "suffix each subnet with…" rather than "suffix each Name tag with…".

[pulumi-bot]

This PR has been shipped in release v3.8.0.