fix(cdk): pin VPC to AgentCore-supported availability zones

cdk/package.json

@@ -20,11 +20,13 @@
     "@aws-sdk/client-bedrock-agentcore": "^3.1078.0",
     "@aws-sdk/client-bedrock-runtime": "^3.1078.0",
     "@aws-sdk/client-dynamodb": "^3.1078.0",
+    "@aws-sdk/client-ec2": "^3.1078.0",
     "@aws-sdk/client-ecs": "^3.1078.0",
     "@aws-sdk/client-lambda": "^3.1078.0",
     "@aws-sdk/client-lambda-microvms": "^3.1098.0",
     "@aws-sdk/client-s3": "^3.1078.0",
     "@aws-sdk/client-secrets-manager": "^3.1078.0",
+    "@aws-sdk/client-sts": "^3.1078.0",
     "@aws-sdk/credential-provider-node": "^3.972.61",
     "@aws-sdk/lib-dynamodb": "^3.1078.0",
     "@aws-sdk/s3-presigned-post": "^3.1078.0",

cdk/src/constructs/agent-vpc.ts

@@ -26,16 +26,63 @@ import { Construct } from 'constructs';
 /** HTTPS port — the only egress allowed from the Runtime ENIs. */
 const HTTPS_PORT = 443;
 
+/**
+ * Default zone count. Kept equal to `AUTO_PIN_AZ_COUNT` in
+ * `constructs/agentcore-azs.ts` so auto-pinning does not change the topology of
+ * a stack that deploys fine today; the coupling is asserted in
+ * `test/constructs/agentcore-azs.test.ts`.
+ */
+const DEFAULT_AGENT_VPC_AZS = 2;
+
+/** AgentCore high-availability floor: at least two zones. */
+const MIN_AGENT_VPC_AZS = 2;
+
 /**
  * Properties for the AgentVpc construct.
  */
 export interface AgentVpcProps {
   /**
    * Maximum number of availability zones to use.
+   *
+   * Ignored when {@link availabilityZones} is provided (CDK does not allow
+   * both `maxAzs` and an explicit zone list on the same VPC).
    * @default 2
    */
   readonly maxAzs?: number;
 
+  /**
+   * Explicit list of availability-zone *names* (e.g. `['us-east-1b', 'us-east-1c']`)
+   * to place the VPC — and therefore the AgentCore Runtime ENIs — into.
+   *
+   * AgentCore only supports a subset of the physical availability zones in a
+   * region, and AZ *names* are aliased per-account to physical zone IDs (so
+   * `us-east-1a` is not the same physical zone across accounts). When CDK is
+   * left to pick zones by name (the `maxAzs` default) it can land the Runtime
+   * subnets in a zone AgentCore does not support, and the
+   * `AWS::BedrockAgentCore::Runtime` resource fails to stabilize with
+   * `NotStabilized` ("subnets are in unsupported availability zones"), rolling
+   * back the whole stack.
+   *
+   * Pin this to AZ names whose physical zone IDs are AgentCore-supported to
+   * make a fresh deploy deterministic regardless of the account's
+   * name → zone-ID mapping. The supported zone-ID set differs per region and
+   * can change over time — see the AWS
+   * {@link https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html#agentcore-supported-azs Supported Availability Zones}
+   * table, and the per-region `AGENTCORE_SUPPORTED_AZ_IDS` map in
+   * `constructs/agentcore-azs.ts`.
+   *
+   * Callers normally don't set this directly: `resolveAgentCoreAzs` (invoked
+   * from `main.ts`) auto-selects supported zone names for the target account,
+   * or honors the validated `agentcore:availabilityZones` context override, and
+   * passes the result through `AgentStackProps.agentCoreAvailabilityZones`.
+   *
+   * Mutually exclusive with {@link maxAzs} — supplying both throws, matching
+   * `ec2.Vpc`'s own contract rather than silently ignoring one of them.
+   * Must list at least two zones (AgentCore high-availability guidance).
+   * @default - CDK selects the first `maxAzs` zones by name
+   */
+  readonly availabilityZones?: string[];
+
   /**
    * Number of NAT gateways to provision.
    * @default 1
@@ -66,13 +113,35 @@ export class AgentVpc extends Construct {
   constructor(scope: Construct, id: string, props: AgentVpcProps = {}) {
     super(scope, id);
 
-    const maxAzs = props.maxAzs ?? 2;
+    const pinnedAzs = props.availabilityZones;
+
+    // `ec2.Vpc` rejects `availabilityZones` + `maxAzs` together. Surface that as
+    // our own error instead of spreading one away silently: a caller who set
+    // both has a wrong mental model and should hear about it.
+    if (pinnedAzs?.length && props.maxAzs !== undefined) {
+      throw new Error(
+        'AgentVpc supports availabilityZones or maxAzs, but not both — '
+        + 'an explicit zone list already fixes the zone count.',
+      );
+    }
+    if (pinnedAzs && pinnedAzs.length < MIN_AGENT_VPC_AZS) {
+      throw new Error(
+        `AgentVpc requires at least ${MIN_AGENT_VPC_AZS} availability zones for AgentCore high `
+        + `availability; got ${JSON.stringify(pinnedAzs)}.`,
+      );
+    }
+
+    const maxAzs = props.maxAzs ?? DEFAULT_AGENT_VPC_AZS;
     const natGateways = props.natGateways ?? 1;
     const removalPolicy = props.removalPolicy ?? RemovalPolicy.DESTROY;
 
     // --- VPC ---
+    // When explicit AZs are provided (to target AgentCore-supported physical
+    // zones), pass them directly and omit maxAzs — CDK does not allow both.
     this.vpc = new ec2.Vpc(this, 'Vpc', {
-      maxAzs,
+      ...(pinnedAzs?.length
+        ? { availabilityZones: pinnedAzs }
+        : { maxAzs }),
       natGateways,
       restrictDefaultSecurityGroup: true,
       subnetConfiguration: [