alchemy 2.0.0-beta.56 → 2.0.0-beta.57

package/src/AWS/EC2/SecurityGroup.ts

@@ -174,6 +174,178 @@ export interface SecurityGroup extends Resource<
   never,
   Providers
 > {}
+/**
+ * An EC2 security group — a stateful virtual firewall that controls inbound
+ * (`ingress`) and outbound (`egress`) traffic for resources in a VPC. Rules can
+ * allow traffic from CIDR ranges, IPv6 ranges, managed prefix lists, or other
+ * security groups. Because it is stateful, return traffic for an allowed
+ * connection is permitted automatically regardless of the opposite-direction
+ * rules.
+ *
+ * If no `egress` rules are specified, all outbound traffic is allowed by
+ * default. Changing the `vpcId` or `groupName` replaces the security group.
+ *
+ * @resource
+ * @section Creating a Security Group
+ * Every security group belongs to a VPC. `groupName` and `description` are
+ * optional — alchemy generates a deterministic name and a default description
+ * when they are omitted. Both the VPC and the name are immutable, so changing
+ * either replaces the group.
+ *
+ * @example Empty Security Group
+ * ```typescript
+ * const sg = yield* AWS.EC2.SecurityGroup("AppSg", {
+ *   vpcId: vpc.vpcId,
+ * });
+ * ```
+ *
+ * With no rules, this group denies all inbound traffic and (since no `egress` is
+ * given) allows all outbound. It's a useful starting point you attach rules to
+ * later, or a target other groups can reference.
+ *
+ * @example Named group with a description
+ * ```typescript
+ * const sg = yield* AWS.EC2.SecurityGroup("AppSg", {
+ *   vpcId: vpc.vpcId,
+ *   groupName: "app-tier",
+ *   description: "Application tier security group",
+ * });
+ * ```
+ *
+ * Set an explicit `groupName` when you need a stable, human-readable identifier
+ * (for example to reference the group by name elsewhere). The `description` is
+ * shown in the EC2 console and cannot be changed after creation.
+ *
+ * @section Ingress Rules
+ * Inbound rules are declared inline via `ingress`. Each rule specifies an
+ * `ipProtocol` (`tcp`, `udp`, `icmp`, or `-1` for all), an optional port range
+ * (`fromPort`/`toPort`), and a source — most commonly an IPv4 `cidrIpv4`.
+ *
+ * @example Allow HTTP and HTTPS from anywhere
+ * ```typescript
+ * const webSg = yield* AWS.EC2.SecurityGroup("WebSecurityGroup", {
+ *   vpcId: vpc.vpcId,
+ *   description: "Web tier security group",
+ *   ingress: [
+ *     {
+ *       ipProtocol: "tcp",
+ *       fromPort: 80,
+ *       toPort: 80,
+ *       cidrIpv4: "0.0.0.0/0",
+ *       description: "Allow HTTP",
+ *     },
+ *     {
+ *       ipProtocol: "tcp",
+ *       fromPort: 443,
+ *       toPort: 443,
+ *       cidrIpv4: "0.0.0.0/0",
+ *       description: "Allow HTTPS",
+ *     },
+ *   ],
+ *   tags: { Name: "web-sg" },
+ * });
+ * ```
+ *
+ * Two rules open the standard web ports to the whole internet (`0.0.0.0/0`).
+ * Setting `fromPort` equal to `toPort` opens a single port; widen the range to
+ * open a contiguous span.
+ *
+ * @section Egress Rules
+ * Outbound traffic is governed by `egress`. If you omit it entirely, the group
+ * keeps AWS's default "allow all outbound" rule. Supplying `egress` replaces
+ * that default with exactly the rules you list — so you must re-add an
+ * allow-all rule if you still want unrestricted outbound.
+ *
+ * @example Restrict outbound to HTTPS only
+ * ```typescript
+ * const lockedSg = yield* AWS.EC2.SecurityGroup("LockedSg", {
+ *   vpcId: vpc.vpcId,
+ *   description: "Outbound restricted to HTTPS",
+ *   egress: [
+ *     {
+ *       ipProtocol: "tcp",
+ *       fromPort: 443,
+ *       toPort: 443,
+ *       cidrIpv4: "0.0.0.0/0",
+ *       description: "Allow outbound HTTPS",
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * This locks egress down to port 443 only — useful for instances that should
+ * only call out to HTTPS APIs. Any other outbound traffic (DNS, NTP, etc.) would
+ * need explicit rules added here.
+ *
+ * @section Referencing Other Groups
+ * Instead of a CIDR, a rule's source can be another security group via
+ * `referencedGroupId`. This is the idiomatic way to express tier-to-tier trust
+ * ("the database accepts connections from anything in the app tier") without
+ * pinning IP addresses.
+ *
+ * @example Database tier allowing traffic from the web tier
+ * ```typescript
+ * const dbSg = yield* AWS.EC2.SecurityGroup("DbSecurityGroup", {
+ *   vpcId: vpc.vpcId,
+ *   description: "Database tier security group",
+ *   ingress: [
+ *     {
+ *       ipProtocol: "tcp",
+ *       fromPort: 5432,
+ *       toPort: 5432,
+ *       referencedGroupId: webSg.groupId,
+ *       description: "Allow PostgreSQL from web tier",
+ *     },
+ *   ],
+ *   tags: { Name: "db-sg" },
+ * });
+ * ```
+ *
+ * Only instances in `webSg` can reach PostgreSQL on this group, regardless of
+ * their IPs. As the web tier scales up and down, the rule keeps working without
+ * any change.
+ *
+ * @section IPv6, Prefix Lists & ICMP
+ * Beyond IPv4 CIDRs, a rule source can be an IPv6 range (`cidrIpv6`) or a managed
+ * prefix list (`prefixListId`). For ICMP, set `ipProtocol: "icmp"` and use
+ * `fromPort`/`toPort` as the ICMP type and code (`-1` for all).
+ *
+ * @example Mixed IPv6, prefix-list, and ICMP rules
+ * ```typescript
+ * const sg = yield* AWS.EC2.SecurityGroup("EdgeSg", {
+ *   vpcId: vpc.vpcId,
+ *   description: "Edge security group",
+ *   ingress: [
+ *     {
+ *       ipProtocol: "tcp",
+ *       fromPort: 443,
+ *       toPort: 443,
+ *       cidrIpv6: "::/0",
+ *       description: "Allow HTTPS over IPv6",
+ *     },
+ *     {
+ *       ipProtocol: "tcp",
+ *       fromPort: 22,
+ *       toPort: 22,
+ *       prefixListId: "pl-0123456789abcdef0",
+ *       description: "Allow SSH from corporate prefix list",
+ *     },
+ *     {
+ *       ipProtocol: "icmp",
+ *       fromPort: -1,
+ *       toPort: -1,
+ *       cidrIpv4: "10.0.0.0/16",
+ *       description: "Allow all ICMP from within the VPC",
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * Prefix lists let you reference a centrally-maintained set of CIDRs (e.g. your
+ * corporate egress IPs) by ID, so the rule updates automatically as the list
+ * changes. The ICMP rule with type/code `-1` permits ping and other ICMP within
+ * the VPC.
+ */
 export const SecurityGroup = Resource<SecurityGroup>("AWS.EC2.SecurityGroup");
 
 export const SecurityGroupProvider = () =>
@@ -364,18 +536,30 @@ export const SecurityGroupProvider = () =>
           // Ensure — create the SG when missing.
           if (sg === undefined) {
             yield* session.note(`Creating Security Group: ${groupName}`);
-            const result = yield* ec2.createSecurityGroup({
-              GroupName: groupName,
-              Description: news.description ?? "Managed by Alchemy",
-              VpcId: news.vpcId as string,
-              TagSpecifications: [
-                {
-                  ResourceType: "security-group",
-                  Tags: createTagsList(desiredTags),
-                },
-              ],
-              DryRun: false,
-            });
+            const result = yield* ec2
+              .createSecurityGroup({
+                GroupName: groupName,
+                Description: news.description ?? "Managed by Alchemy",
+                VpcId: news.vpcId as string,
+                TagSpecifications: [
+                  {
+                    ResourceType: "security-group",
+                    Tags: createTagsList(desiredTags),
+                  },
+                ],
+                DryRun: false,
+              })
+              .pipe(
+                // A just-created VPC can lag visibility to the SG service
+                // (EC2 eventual consistency), so the create races with
+                // `InvalidVpcID.NotFound`. Retry, bounded.
+                Effect.retry({
+                  while: (e) => e._tag === "InvalidVpcID.NotFound",
+                  schedule: Schedule.fixed("1 second").pipe(
+                    Schedule.both(Schedule.recurs(15)),
+                  ),
+                }),
+              );
             const newGroupId = result.GroupId! as SecurityGroupId;
             yield* session.note(`Security Group created: ${newGroupId}`);
             sg = yield* describeSecurityGroup(newGroupId);

package/src/AWS/EC2/SecurityGroupRule.ts

@@ -141,6 +141,146 @@ export interface SecurityGroupRule extends Resource<
   never,
   Providers
 > {}
+/**
+ * A single ingress or egress rule attached to an existing security group,
+ * managed as a standalone resource. Use this when you want to manage a
+ * security group's rules independently of the group itself — for example, to
+ * add rules to a group owned by another stack, or to add rules without
+ * triggering a full re-sync of the group's inline rule set.
+ *
+ * Most properties (protocol, ports, source, `type`) replace the rule when
+ * changed; only `description` and `tags` are updated in place.
+ *
+ * @resource
+ * @section Ingress vs Egress
+ * The `type` field decides the direction: `"ingress"` for inbound rules and
+ * `"egress"` for outbound. Everything else (protocol, ports, source) is shared
+ * between the two directions.
+ *
+ * @example Inbound HTTPS from anywhere
+ * ```typescript
+ * const httpsRule = yield* AWS.EC2.SecurityGroupRule("HttpsIngress", {
+ *   groupId: sg.groupId,
+ *   type: "ingress",
+ *   ipProtocol: "tcp",
+ *   fromPort: 443,
+ *   toPort: 443,
+ *   cidrIpv4: "0.0.0.0/0",
+ *   description: "Allow HTTPS",
+ * });
+ * ```
+ *
+ * Opens TCP 443 inbound from the entire internet on the target group. A single
+ * port is expressed by setting `fromPort` and `toPort` to the same value.
+ *
+ * @example Outbound to a database port
+ * ```typescript
+ * const egressRule = yield* AWS.EC2.SecurityGroupRule("DbEgress", {
+ *   groupId: sg.groupId,
+ *   type: "egress",
+ *   ipProtocol: "tcp",
+ *   fromPort: 5432,
+ *   toPort: 5432,
+ *   cidrIpv4: "10.0.0.0/16",
+ *   description: "Allow PostgreSQL to the VPC",
+ * });
+ * ```
+ *
+ * An egress rule restricts where the group's members may connect out to — here,
+ * only PostgreSQL within the VPC CIDR. Adding any egress rule to a group
+ * supersedes the default allow-all-outbound behavior.
+ *
+ * @section Rule Sources
+ * A rule's source (for ingress) or destination (for egress) is exactly one of:
+ * an IPv4 CIDR (`cidrIpv4`), an IPv6 CIDR (`cidrIpv6`), another security group
+ * (`referencedGroupId`), or a managed prefix list (`prefixListId`).
+ *
+ * @example Allow traffic from another security group
+ * ```typescript
+ * const dbFromWeb = yield* AWS.EC2.SecurityGroupRule("DbFromWeb", {
+ *   groupId: dbSg.groupId,
+ *   type: "ingress",
+ *   ipProtocol: "tcp",
+ *   fromPort: 5432,
+ *   toPort: 5432,
+ *   referencedGroupId: webSg.groupId,
+ *   description: "Allow PostgreSQL from web tier",
+ * });
+ * ```
+ *
+ * Referencing `webSg` rather than a CIDR means any instance in the web tier can
+ * reach the database, even as the tier's IPs change. This is the preferred way
+ * to wire trust between tiers.
+ *
+ * @example Allow an IPv6 range
+ * ```typescript
+ * const ipv6Rule = yield* AWS.EC2.SecurityGroupRule("HttpsIpv6", {
+ *   groupId: sg.groupId,
+ *   type: "ingress",
+ *   ipProtocol: "tcp",
+ *   fromPort: 443,
+ *   toPort: 443,
+ *   cidrIpv6: "::/0",
+ *   description: "Allow HTTPS over IPv6",
+ * });
+ * ```
+ *
+ * Use `cidrIpv6` for dual-stack workloads; `::/0` is the IPv6 equivalent of
+ * `0.0.0.0/0`. IPv4 and IPv6 are separate rules — you'd pair this with a
+ * `cidrIpv4` rule to cover both.
+ *
+ * @example Allow from a managed prefix list
+ * ```typescript
+ * const sshRule = yield* AWS.EC2.SecurityGroupRule("SshFromCorp", {
+ *   groupId: sg.groupId,
+ *   type: "ingress",
+ *   ipProtocol: "tcp",
+ *   fromPort: 22,
+ *   toPort: 22,
+ *   prefixListId: "pl-0123456789abcdef0",
+ *   description: "Allow SSH from the corporate prefix list",
+ * });
+ * ```
+ *
+ * A `prefixListId` references a centrally-managed set of CIDRs by ID, so the
+ * rule's effective ranges update automatically whenever the prefix list does.
+ *
+ * @section Protocols & Ports
+ * `ipProtocol` accepts `tcp`, `udp`, `icmp`/`icmpv6`, a protocol number, or `-1`
+ * for all protocols. For ICMP, `fromPort` is the ICMP type and `toPort` is the
+ * ICMP code, with `-1` meaning "all".
+ *
+ * @example Allow all traffic from a trusted CIDR
+ * ```typescript
+ * const allRule = yield* AWS.EC2.SecurityGroupRule("AllFromVpc", {
+ *   groupId: sg.groupId,
+ *   type: "ingress",
+ *   ipProtocol: "-1",
+ *   cidrIpv4: "10.0.0.0/16",
+ *   description: "Allow all protocols from within the VPC",
+ * });
+ * ```
+ *
+ * With `ipProtocol: "-1"`, ports are ignored and every protocol is permitted —
+ * appropriate only for fully trusted sources such as your own VPC CIDR.
+ *
+ * @example Allow ICMP echo (ping)
+ * ```typescript
+ * const icmpRule = yield* AWS.EC2.SecurityGroupRule("AllowPing", {
+ *   groupId: sg.groupId,
+ *   type: "ingress",
+ *   ipProtocol: "icmp",
+ *   fromPort: 8,
+ *   toPort: 0,
+ *   cidrIpv4: "10.0.0.0/16",
+ *   description: "Allow ICMP echo request",
+ * });
+ * ```
+ *
+ * For ICMP the port fields carry the type and code: type `8` / code `0` is an
+ * echo request (ping). Use `fromPort: -1, toPort: -1` to allow every ICMP
+ * type/code instead.
+ */
 export const SecurityGroupRule = Resource<SecurityGroupRule>(
   "AWS.EC2.SecurityGroupRule",
 );

package/src/AWS/EC2/Subnet.ts

@@ -211,6 +211,138 @@ export interface Subnet extends Resource<
   never,
   Providers
 > {}
+/**
+ * A subnet within a VPC — a range of IP addresses bound to a single
+ * Availability Zone where you place instances and other resources. Create
+ * public subnets (with `mapPublicIpOnLaunch`) for internet-facing resources
+ * and private subnets for internal ones.
+ *
+ * Changing the `vpcId`, `cidrBlock`, availability zone, or an IPAM/IPv6 pool
+ * replaces the subnet.
+ *
+ * @resource
+ * @section Creating a Subnet
+ * A subnet carves a smaller CIDR range out of its parent VPC's block. The
+ * `cidrBlock` must be a subset of the VPC CIDR and must not overlap any sibling
+ * subnet. You can also let AWS IPAM allocate the range via `ipv4IpamPoolId` +
+ * `ipv4NetmaskLength`.
+ *
+ * @example Basic Subnet
+ * ```typescript
+ * const subnet = yield* AWS.EC2.Subnet("TestSubnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ * });
+ * ```
+ *
+ * The minimal subnet: a `/24` (256 addresses) inside the VPC. Without an
+ * explicit `availabilityZone`, AWS picks one for you.
+ *
+ * @section Availability Zone Placement
+ * Each subnet lives in exactly one AZ. Pin it with `availabilityZone` (the zone
+ * name, e.g. `us-east-1a`) or `availabilityZoneId` (the stable zone ID, e.g.
+ * `use1-az1`) to spread tiers across zones for high availability.
+ *
+ * @example Subnet pinned to an Availability Zone
+ * ```typescript
+ * const subnet = yield* AWS.EC2.Subnet("Az1Subnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ *   availabilityZone: "us-east-1a",
+ * });
+ * ```
+ *
+ * Pinning the AZ lets you place a matching subnet in `us-east-1b` and run
+ * resources redundantly across zones. Use `availabilityZoneId` instead when you
+ * need the physical zone to line up across different AWS accounts.
+ *
+ * @section Public IP Assignment
+ * @example Public subnet
+ * ```typescript
+ * const publicSubnet = yield* AWS.EC2.Subnet("PublicSubnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ *   availabilityZone: "us-east-1a",
+ *   mapPublicIpOnLaunch: true,
+ *   tags: { Name: "public-1a", Tier: "public" },
+ * });
+ * ```
+ *
+ * `mapPublicIpOnLaunch: true` makes this a "public" subnet — instances launched
+ * here automatically get a public IPv4 address. Combine it with an internet
+ * gateway route so those instances can reach the internet.
+ *
+ * @section IPv6 Subnets
+ * For dual-stack VPCs, give the subnet an IPv6 `cidrBlock`, auto-assign IPv6
+ * addresses on launch with `assignIpv6AddressOnCreation`, and optionally enable
+ * `enableDns64` so the Amazon DNS resolver synthesizes IPv6 addresses for
+ * IPv4-only destinations (NAT64).
+ *
+ * @example IPv6-enabled subnet
+ * ```typescript
+ * const subnet = yield* AWS.EC2.Subnet("Ipv6Subnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ *   ipv6CidrBlock: "2600:1f18:abcd:1234::/64",
+ *   assignIpv6AddressOnCreation: true,
+ *   enableDns64: true,
+ * });
+ * ```
+ *
+ * Instances launched here receive an IPv6 address automatically, and `enableDns64`
+ * lets them reach IPv4-only services through a NAT gateway. The IPv6 `/64` must
+ * come from the parent VPC's IPv6 block.
+ *
+ * @section DNS Hostname Options
+ * Control what hostnames instances receive on launch. `hostnameType` chooses
+ * between IP-based names (`ip-name`) and resource-based names (`resource-name`),
+ * and the `enableResourceNameDnsARecordOnLaunch` /
+ * `enableResourceNameDnsAAAARecordOnLaunch` flags register A / AAAA records for
+ * resource-name hosts.
+ *
+ * @example Resource-name DNS hostnames
+ * ```typescript
+ * const subnet = yield* AWS.EC2.Subnet("ResourceNameSubnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ *   hostnameType: "resource-name",
+ *   enableResourceNameDnsARecordOnLaunch: true,
+ *   enableResourceNameDnsAAAARecordOnLaunch: true,
+ * });
+ * ```
+ *
+ * Resource-name hostnames are derived from the instance ID rather than its IP,
+ * so they stay stable across stop/start. Enabling the A/AAAA records makes those
+ * names resolvable over IPv4 and IPv6.
+ *
+ * @section Public & Private Tiers
+ * @example A public and a private subnet in one VPC
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   enableDnsSupport: true,
+ *   enableDnsHostnames: true,
+ * });
+ *
+ * const publicSubnet = yield* AWS.EC2.Subnet("PublicSubnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ *   availabilityZone: "us-east-1a",
+ *   mapPublicIpOnLaunch: true,
+ * });
+ *
+ * const privateSubnet = yield* AWS.EC2.Subnet("PrivateSubnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.10.0/24",
+ *   availabilityZone: "us-east-1a",
+ * });
+ * ```
+ *
+ * The canonical two-tier pattern: a public subnet (auto public IPs, routed to an
+ * internet gateway) for load balancers and a private subnet (no public IPs) for
+ * application and database instances. Both share the same AZ here, but in
+ * production you'd replicate the pair across AZs.
+ */
 export const Subnet = Resource<Subnet>("AWS.EC2.Subnet");
 
 export const SubnetProvider = () =>
@@ -417,7 +549,10 @@ export const SubnetProvider = () =>
             .pipe(
               Effect.tapError(Effect.logDebug),
               Effect.catchTag("InvalidSubnetID.NotFound", () => Effect.void),
-              // Retry on dependency violations (resources still being deleted)
+              // Retry on dependency violations (resources still being deleted).
+              // ENIs from a just-deleted ALB or CloudFront VPC origin can take
+              // several minutes to detach after the owning resource is gone, so
+              // budget ~12 min (fast exponential start, capped at 30s steps).
               Effect.retry({
                 while: (e) => {
                   // DependencyViolation means there are still dependent resources
@@ -425,7 +560,8 @@ export const SubnetProvider = () =>
                   return e._tag === "DependencyViolation";
                 },
                 schedule: Schedule.exponential(1000, 1.5).pipe(
-                  Schedule.both(Schedule.recurs(10)), // Try up to 10 times
+                  Schedule.either(Schedule.spaced("30 seconds")),
+                  Schedule.both(Schedule.recurs(30)),
                   Schedule.tapOutput(([, attempt]) =>
                     session.note(
                       `Waiting for dependencies to clear... (attempt ${attempt + 1})`,

package/src/AWS/EC2/Vpc.ts

@@ -158,11 +158,149 @@ export interface Vpc extends Resource<
       ipv6Pool?: string;
     }>;
 
+    /**
+     * The tags currently assigned to the VPC, including alchemy auto-tags.
+     */
     tags?: Record<string, string>;
   },
   never,
   Providers
 > {}
+/**
+ * An Amazon VPC (Virtual Private Cloud) — an isolated virtual network that is
+ * the root of any custom AWS networking topology. Subnets, route tables,
+ * gateways, security groups, and instances are all created inside a VPC.
+ *
+ * Changing the `cidrBlock`, `instanceTenancy`, or an IPAM/IPv6 pool replaces
+ * the VPC.
+ *
+ * @resource
+ * @section Creating a VPC
+ * A VPC is defined by a private IPv4 address range (`cidrBlock`). Pick a block
+ * from the RFC 1918 private space (e.g. `10.0.0.0/16`) that is large enough to
+ * subdivide into subnets across your Availability Zones.
+ *
+ * @example Basic VPC
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ * });
+ * ```
+ *
+ * A `/16` gives you 65,536 addresses to carve into subnets — enough headroom
+ * for a multi-AZ, multi-tier network. This is the minimal config every other
+ * networking resource builds on.
+ *
+ * @example Allocating IPv4 from an IPAM pool
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   ipv4IpamPoolId: "ipam-pool-0123456789abcdef0",
+ *   ipv4NetmaskLength: 16,
+ * });
+ * ```
+ *
+ * Instead of hard-coding `cidrBlock`, let AWS IPAM hand out a non-overlapping
+ * range of the requested size. Use this when an organization centrally manages
+ * address space to avoid CIDR collisions between accounts.
+ *
+ * @section DNS Resolution
+ * Two independent toggles control DNS behavior inside the VPC. `enableDnsSupport`
+ * lets instances resolve names via the Amazon DNS server; `enableDnsHostnames`
+ * additionally assigns public DNS hostnames to instances with public IPs.
+ *
+ * @example Enable DNS support and hostnames
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   enableDnsSupport: true,
+ *   enableDnsHostnames: true,
+ * });
+ * ```
+ *
+ * Enable both when instances need public DNS names or when you rely on private
+ * hosted zones and VPC endpoints, which require DNS resolution to function.
+ *
+ * @section Instance Tenancy
+ * @example Dedicated tenancy
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   instanceTenancy: "dedicated",
+ * });
+ * ```
+ *
+ * Forcing `"dedicated"` tenancy ensures every instance launched in the VPC runs
+ * on single-tenant hardware — required by some compliance regimes, but more
+ * expensive than the `"default"` shared tenancy. This property cannot be
+ * changed after creation without replacing the VPC.
+ *
+ * @section IPv6 Addressing
+ * A VPC can carry an IPv6 `/56` block alongside its IPv4 range. The block can
+ * come from Amazon's pool, an IPAM pool, or your own BYOIP pool
+ * (`ipv6CidrBlock` + `ipv6Pool`, optionally scoped to a
+ * `ipv6CidrBlockNetworkBorderGroup`).
+ *
+ * @example Amazon-provided IPv6 block
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   amazonProvidedIpv6CidrBlock: true,
+ * });
+ * ```
+ *
+ * Requests an Amazon-assigned IPv6 `/56`, the simplest way to make a VPC
+ * dual-stack. Pair it with IPv6-enabled subnets and an egress-only internet
+ * gateway for outbound-only IPv6 connectivity.
+ *
+ * @example IPv6 from an IPAM pool
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   ipv6IpamPoolId: "ipam-pool-0fedcba9876543210",
+ *   ipv6NetmaskLength: 56,
+ * });
+ * ```
+ *
+ * Draws the IPv6 block from a centrally-managed IPAM pool instead of Amazon's
+ * pool, giving you deterministic, organization-governed IPv6 ranges.
+ *
+ * @section Composing a Network
+ * @example VPC with a subnet
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   enableDnsSupport: true,
+ *   enableDnsHostnames: true,
+ * });
+ *
+ * const subnet = yield* AWS.EC2.Subnet("PublicSubnet", {
+ *   vpcId: vpc.vpcId,
+ *   cidrBlock: "10.0.1.0/24",
+ *   availabilityZone: "us-east-1a",
+ *   mapPublicIpOnLaunch: true,
+ * });
+ * ```
+ *
+ * Passing `vpc.vpcId` into a `Subnet` is how you build out a topology — the
+ * subnet's CIDR must fall within the VPC's `cidrBlock`. Add route tables,
+ * gateways, and security groups the same way.
+ *
+ * @section Tagging
+ * @example Tagging a VPC
+ * ```typescript
+ * const vpc = yield* AWS.EC2.Vpc("MyVpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   tags: {
+ *     Name: "production-vpc",
+ *     Environment: "production",
+ *   },
+ * });
+ * ```
+ *
+ * User tags are merged with alchemy's auto-tags (`alchemy::stack`,
+ * `alchemy::stage`, `alchemy::id`), which brand the VPC as managed by your
+ * stack. The `Name` tag is what surfaces in the EC2 console.
+ */
 export const Vpc = Resource<Vpc>("AWS.EC2.VPC");
 
 /**