fix(cdk): accept -c JSON-string AZ override + cap auto-pin at 2 (#353) Follow-up to the auto-pin review on #358. - resolveAgentCoreAzOverride now JSON-parses a string context value, so the documented '-c agentcore:availabilityZones=[...]' recovery path works identically to the cdk.context.json array form (CDK delivers -c values as raw strings). A non-JSON string is left as-is and still fails the array check with the same clear, key-named error, so true typos error out. - Auto-pin now pins the first MIN_AGENTCORE_AZS (2) supported zones instead of every match, matching AgentVpc's default maxAzs so enabling auto-pin no longer silently widens a working 2-AZ account to all supported zones (e.g. 3 AZs / 6 subnets). - DEPLOYMENT_GUIDE: sharpened the contrast that auto-pin is local-deploy-only and the CI/CD (deploy.yml) artifact is env-agnostic and must set the override; added an explicit -c example now that it parses. - Tests: added JSON-string override (success) and JSON-non-array (throws) cases; updated the auto-pin test to assert the 2-zone cap.

Author: bgagent

cdk/src/constructs/agentcore-azs.ts

@@ -100,10 +100,23 @@ export interface ResolveAgentCoreAzsOptions {
  *   or lists fewer than {@link MIN_AGENTCORE_AZS} zones.
  */
 export function resolveAgentCoreAzOverride(node: Node): string[] | undefined {
-  const override = node.tryGetContext(AGENTCORE_AZS_CONTEXT_KEY);
-  if (override === undefined || override === null) {
+  const raw = node.tryGetContext(AGENTCORE_AZS_CONTEXT_KEY);
+  if (raw === undefined || raw === null) {
     return undefined;
   }
+  // `cdk.context.json` delivers a real array, but `-c key=value` on the CLI
+  // (the recovery path this feature exists for) delivers a raw string. Parse the
+  // string form so both behave identically. A non-JSON string — a true typo —
+  // is left as-is and fails the Array.isArray check below with the same clear,
+  // key-named error.
+  let override: unknown = raw;
+  if (typeof raw === 'string') {
+    try {
+      override = JSON.parse(raw);
+    } catch {
+      override = raw;
+    }
+  }
   if (!Array.isArray(override)) {
     throw new Error(
       `Context '${AGENTCORE_AZS_CONTEXT_KEY}' must be a JSON array of availability-zone names `
@@ -176,10 +189,11 @@ async function defaultDescribeAzs(region: string): Promise<AvailabilityZoneInfo[
  *     context value always wins (works even in env-agnostic synth, which is how
  *     the CI-built artifact and production stack pin zones).
  *  2. **Auto-pin (default path)** — when synth has a concrete account + region,
- *     resolve the account's name -> zone-ID mapping and intersect it with
- *     {@link AGENTCORE_SUPPORTED_AZ_IDS} for the region, so a fresh local
- *     `cdk deploy` lands only in supported zones without account-specific
- *     guesswork.
+ *     resolve the account's name -> zone-ID mapping, intersect it with
+ *     {@link AGENTCORE_SUPPORTED_AZ_IDS} for the region, and pin the first
+ *     {@link MIN_AGENTCORE_AZS} supported zones (matching AgentVpc's default
+ *     `maxAzs`), so a fresh local `cdk deploy` lands only in supported zones
+ *     without account-specific guesswork or widening the topology.
  *  3. **Fallback** — env-agnostic synth (token/undefined account or region), an
  *     unknown region, a failed lookup, or fewer than {@link MIN_AGENTCORE_AZS}
  *     supported zones all return `undefined`, leaving CDK's default AZ selection
@@ -220,7 +234,11 @@ export async function resolveAgentCoreAzs(options: ResolveAgentCoreAzsOptions):
     const zones = await describeAzs(region);
     const names = selectSupportedAzNames(region, zones);
     if (names.length >= MIN_AGENTCORE_AZS) {
-      pinnedZones = names;
+      // Pin exactly MIN_AGENTCORE_AZS zones — the HA floor, matching AgentVpc's
+      // default `maxAzs` (2). Pinning every supported zone would silently widen
+      // an account that deploys fine today from 2 AZs to all supported (often 3
+      // -> 6 subnets), so cap the selection to keep the topology stable.
+      pinnedZones = names.slice(0, MIN_AGENTCORE_AZS);
     } else {
       Annotations.of(scope).addWarning(
         `[AgentCore AZs] Found only ${names.length} AgentCore-supported availability zone(s) in `

cdk/test/constructs/agentcore-azs.test.ts

@@ -84,12 +84,26 @@ describe('resolveAgentCoreAzOverride', () => {
     ).toEqual(override);
   });
 
-  it('throws on a non-array override (typo guard)', () => {
+  it('throws on a bare (non-JSON) string override (typo guard)', () => {
     expect(() =>
       resolveAgentCoreAzOverride(nodeWithContext({ [AGENTCORE_AZS_CONTEXT_KEY]: 'us-east-1b' })),
     ).toThrow(/must be a JSON array/);
   });
 
+  it('parses a JSON-string array (the `-c key=value` CLI form)', () => {
+    // CDK delivers `-c agentcore:availabilityZones=[...]` as a raw string, not a
+    // parsed array — the documented mid-rollback recovery path must still work.
+    expect(
+      resolveAgentCoreAzOverride(nodeWithContext({ [AGENTCORE_AZS_CONTEXT_KEY]: '["us-east-1b","us-east-1c"]' })),
+    ).toEqual(['us-east-1b', 'us-east-1c']);
+  });
+
+  it('throws on a JSON string that does not parse to an array', () => {
+    expect(() =>
+      resolveAgentCoreAzOverride(nodeWithContext({ [AGENTCORE_AZS_CONTEXT_KEY]: '"us-east-1b"' })),
+    ).toThrow(/must be a JSON array/);
+  });
+
   it('throws on a non-string / empty entry', () => {
     expect(() =>
       resolveAgentCoreAzOverride(nodeWithContext({ [AGENTCORE_AZS_CONTEXT_KEY]: ['us-east-1b', ''] })),
@@ -166,15 +180,17 @@ describe('resolveAgentCoreAzs', () => {
     expect(describeAzs).not.toHaveBeenCalled();
   });
 
-  it('auto-pins to the account supported zone names for a concrete env', async () => {
+  it('auto-pins the first two supported zone names (capped) for a concrete env', async () => {
+    // US_EAST_1_ZONES has three supported zones (az2/az4/az1 -> a/b/d); auto-pin
+    // caps at two to match AgentVpc's default maxAzs and avoid widening topology.
     const describeAzs = jest.fn<Promise<AvailabilityZoneInfo[]>, [string]>().mockResolvedValue(US_EAST_1_ZONES);
     const result = await resolveAgentCoreAzs({
       scope: scopeWithContext(),
       account: '123456789012',
       region: 'us-east-1',
       describeAzs,
     });
-    expect(result).toEqual(['us-east-1a', 'us-east-1b', 'us-east-1d']);
+    expect(result).toEqual(['us-east-1a', 'us-east-1b']);
     expect(describeAzs).toHaveBeenCalledWith('us-east-1');
   });
 

docs/guides/DEPLOYMENT_GUIDE.md

@@ -171,22 +171,26 @@ Triggers via `workflow_run` when `build.yml` completes successfully. The pipelin
 
 **Root cause:** AgentCore Runtime only places its network interfaces in a subset of each region's Availability Zones, published as physical **zone IDs** (e.g. `use1-az1`, `use1-az2`, `use1-az4` for `us-east-1`). Zone IDs are stable across accounts, but zone *names* (`us-east-1a`) are aliased per-account — so `us-east-1a` can map to a different physical zone in your account than in another. Left to its default, CDK picks zones by name and can land the Runtime subnets in an unsupported zone. See the AWS [Supported Availability Zones](https://aws.github.io/bedrock-agentcore-starter-toolkit/user-guide/security/agentcore-vpc/#supported-availability-zones) table for the per-region set.
 
-**Default behavior (auto-pin):** When the stack is synthesized with a concrete account and region — the usual local `cdk deploy` / `mise //cdk:deploy` path — it resolves your account's zone name-to-ID mapping (`ec2:DescribeAvailabilityZones`) and pins the VPC to the AZ *names* whose IDs are AgentCore-supported. No action needed for supported regions.
+**Default behavior (auto-pin) — local deploy only:** When the stack is synthesized with a concrete account and region — a local `cdk deploy` / `mise //cdk:deploy`, which resolves credentials at synth time — it reads your account's zone name-to-ID mapping (`ec2:DescribeAvailabilityZones`) and pins the VPC to the first two AZ *names* whose IDs are AgentCore-supported (two matches AgentVpc's default `maxAzs`, so enabling this doesn't widen an already-working topology). No action needed on that path for the regions in the built-in map.
 
-**When you must pin manually:** Env-agnostic synthesis skips auto-pin (there's no bound account to resolve the mapping) — this includes the CI-built artifact deployed by `deploy.yml`, and any region not yet in the built-in supported-AZ map. In those cases, set the `agentcore:availabilityZones` context override:
+**The CI/CD-deployed stack is NOT auto-pinned.** Auto-pin needs a bound account at synth time, and the pipeline doesn't have one: `build.yml` synthesizes `cdk.out` credential-less (env-agnostic), and `deploy.yml` deploys that pre-built artifact (`--app cdk/cdk.out`). So a team deploying through the pipeline falls back to CDK's default AZ selection and **must set the `agentcore:availabilityZones` override to pin zones**. The same applies to any region not yet in the built-in supported-AZ map. To set the override:
 
 1. Discover your account's zone name-to-ID mapping:
    ```bash
    aws ec2 describe-availability-zones --region <region> \
      --query 'AvailabilityZones[].[ZoneName,ZoneId]' --output text
    ```
-2. Pick the zone **names** whose **IDs** are in the AgentCore-supported set for the region (at least two, for high availability).
-3. Set the override in `cdk/cdk.context.json` (or via `-c`), then redeploy:
+2. Pick at least two zone **names** whose **IDs** are in the AgentCore-supported set for the region (high-availability floor).
+3. Set the override — either in `cdk/cdk.context.json`:
    ```json
    { "agentcore:availabilityZones": ["us-east-1b", "us-east-1c"] }
    ```
+   or on the CLI (note the value is a JSON array):
+   ```bash
+   cdk deploy -c 'agentcore:availabilityZones=["us-east-1b","us-east-1c"]'
+   ```
 
-The override is validated at synth time: a non-array, an empty/non-string entry, or fewer than two zones fails the synth with a message naming the key and expected shape. The supported-AZ map and resolution logic live in `cdk/src/constructs/agentcore-azs.ts`.
+The override is validated at synth time (both forms parse identically): a non-array, an empty/non-string entry, or fewer than two zones fails the synth with a message naming the key and expected shape. The supported-AZ map and resolution logic live in `cdk/src/constructs/agentcore-azs.ts`.
 
 ### DNS Query Log Config replacement cascade (upgrading from pre-v0.5)
 

docs/src/content/docs/getting-started/Deployment-guide.md

@@ -175,22 +175,26 @@ Triggers via `workflow_run` when `build.yml` completes successfully. The pipelin
 
 **Root cause:** AgentCore Runtime only places its network interfaces in a subset of each region's Availability Zones, published as physical **zone IDs** (e.g. `use1-az1`, `use1-az2`, `use1-az4` for `us-east-1`). Zone IDs are stable across accounts, but zone *names* (`us-east-1a`) are aliased per-account — so `us-east-1a` can map to a different physical zone in your account than in another. Left to its default, CDK picks zones by name and can land the Runtime subnets in an unsupported zone. See the AWS [Supported Availability Zones](https://aws.github.io/bedrock-agentcore-starter-toolkit/user-guide/security/agentcore-vpc/#supported-availability-zones) table for the per-region set.
 
-**Default behavior (auto-pin):** When the stack is synthesized with a concrete account and region — the usual local `cdk deploy` / `mise //cdk:deploy` path — it resolves your account's zone name-to-ID mapping (`ec2:DescribeAvailabilityZones`) and pins the VPC to the AZ *names* whose IDs are AgentCore-supported. No action needed for supported regions.
+**Default behavior (auto-pin) — local deploy only:** When the stack is synthesized with a concrete account and region — a local `cdk deploy` / `mise //cdk:deploy`, which resolves credentials at synth time — it reads your account's zone name-to-ID mapping (`ec2:DescribeAvailabilityZones`) and pins the VPC to the first two AZ *names* whose IDs are AgentCore-supported (two matches AgentVpc's default `maxAzs`, so enabling this doesn't widen an already-working topology). No action needed on that path for the regions in the built-in map.
 
-**When you must pin manually:** Env-agnostic synthesis skips auto-pin (there's no bound account to resolve the mapping) — this includes the CI-built artifact deployed by `deploy.yml`, and any region not yet in the built-in supported-AZ map. In those cases, set the `agentcore:availabilityZones` context override:
+**The CI/CD-deployed stack is NOT auto-pinned.** Auto-pin needs a bound account at synth time, and the pipeline doesn't have one: `build.yml` synthesizes `cdk.out` credential-less (env-agnostic), and `deploy.yml` deploys that pre-built artifact (`--app cdk/cdk.out`). So a team deploying through the pipeline falls back to CDK's default AZ selection and **must set the `agentcore:availabilityZones` override to pin zones**. The same applies to any region not yet in the built-in supported-AZ map. To set the override:
 
 1. Discover your account's zone name-to-ID mapping:
    ```bash
    aws ec2 describe-availability-zones --region <region> \
      --query 'AvailabilityZones[].[ZoneName,ZoneId]' --output text
    ```
-2. Pick the zone **names** whose **IDs** are in the AgentCore-supported set for the region (at least two, for high availability).
-3. Set the override in `cdk/cdk.context.json` (or via `-c`), then redeploy:
+2. Pick at least two zone **names** whose **IDs** are in the AgentCore-supported set for the region (high-availability floor).
+3. Set the override — either in `cdk/cdk.context.json`:
    ```json
    { "agentcore:availabilityZones": ["us-east-1b", "us-east-1c"] }
    ```
+   or on the CLI (note the value is a JSON array):
+   ```bash
+   cdk deploy -c 'agentcore:availabilityZones=["us-east-1b","us-east-1c"]'
+   ```
 
-The override is validated at synth time: a non-array, an empty/non-string entry, or fewer than two zones fails the synth with a message naming the key and expected shape. The supported-AZ map and resolution logic live in `cdk/src/constructs/agentcore-azs.ts`.
+The override is validated at synth time (both forms parse identically): a non-array, an empty/non-string entry, or fewer than two zones fails the synth with a message naming the key and expected shape. The supported-AZ map and resolution logic live in `cdk/src/constructs/agentcore-azs.ts`.
 
 ### DNS Query Log Config replacement cascade (upgrading from pre-v0.5)