@go-to-k/cdkd 0.30.1 → 0.31.0

package/README.md

@@ -24,7 +24,7 @@
 - **Diff calculation**: Self-implemented resource/property-level diff between desired template and current state
 - **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
 - **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
-- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache and return as soon as the create call returns (CloudFormation always blocks)
+- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
 
 > **Note**: Resource types not covered by either SDK Providers or Cloud Control API cannot be deployed with cdkd. If you encounter an unsupported resource type, deployment will fail with a clear error message.
 
@@ -372,11 +372,11 @@ cdkd state destroy MyStack --region us-east-1
 
 ## `--no-wait`: skip async-resource waits
 
-CloudFront Distributions, RDS Clusters/Instances, and ElastiCache
-typically take 3–15 minutes for AWS to fully propagate. By default
-cdkd waits for them to reach a ready state — the same behavior as
-CloudFormation. Pass `--no-wait` to return as soon as the create call
-returns:
+CloudFront Distributions, RDS Clusters/Instances, ElastiCache, and
+NAT Gateways typically take 1–15 minutes for AWS to fully provision.
+By default cdkd waits for them to reach a ready state — the same
+behavior as CloudFormation. Pass `--no-wait` to return as soon as the
+create call returns:
 
 ```bash
 cdkd deploy --no-wait
@@ -386,6 +386,25 @@ The resource is fully functional once AWS finishes the async
 deployment in the background. CloudFormation has no equivalent — once
 you submit a stack, you wait for everything.
 
+NAT Gateway is included as of v0.31. Provisioning typically takes
+1–2 minutes and is the dominant cost in many VPC stacks; with
+`cdkd deploy --no-wait`, `CreateNatGateway` returns the `NatGatewayId`
+immediately and dependent Routes that only reference the ID can
+proceed against a still-`pending` gateway. AWS continues NAT
+provisioning asynchronously after the deploy returns. Use this only
+when nothing in the deploy flow needs actual NAT-routed egress (e.g.
+no Lambda invoked during deploy that hits the internet).
+
+`--no-wait` is **deploy-only**. `cdkd destroy` always waits for NAT
+Gateway to reach `deleted` state — while the gateway is in
+`deleting` AWS keeps the ENI / EIP / route-table associations
+attached, so any concurrent `DeleteSubnet` / `DeleteInternetGateway`
+/ `DeleteVpc` returns `DependencyViolation` and the destroy enters a
+retry storm. Other `--no-wait` resources (CloudFront / RDS /
+ElastiCache) don't apply to destroy either — their providers are
+already non-blocking on delete because they're leaves in the destroy
+DAG.
+
 ## Other CLI flags
 
 For concurrency knobs (`--concurrency`, `--stack-concurrency`,

package/dist/cli.js

@@ -606,6 +606,10 @@ function validateResourceTimeouts(opts) {
     }
   }
 }
+var noWaitOption = new Option(
+  "--no-wait",
+  "Skip waiting for async resources to stabilize (CloudFront, RDS, ElastiCache, NAT Gateway)"
+);
 var deployOptions = [
   new Option("--concurrency <number>", "Maximum concurrent resource operations").default(10).argParser((value) => parseInt(value, 10)),
   new Option("--stack-concurrency <number>", "Maximum concurrent stack deployments").default(4).argParser((value) => parseInt(value, 10)),
@@ -617,7 +621,7 @@ var deployOptions = [
   new Option("--dry-run", "Show changes without applying").default(false),
   new Option("--skip-assets", "Skip asset publishing").default(false),
   new Option("--no-rollback", "Skip rollback on deployment failure"),
-  new Option("--no-wait", "Skip waiting for async resources (CloudFront, RDS, etc.)"),
+  noWaitOption,
   new Option(
     "-e, --exclusively",
     "Only deploy requested stacks, do not include dependencies"
@@ -7506,7 +7510,11 @@ Error: ${err.message || "Unknown error"}`,
 };
 
 // src/provisioning/providers/custom-resource-provider.ts
-import { InvokeCommand } from "@aws-sdk/client-lambda";
+import {
+  InvokeCommand,
+  waitUntilFunctionActiveV2,
+  waitUntilFunctionUpdatedV2
+} from "@aws-sdk/client-lambda";
 import { PublishCommand } from "@aws-sdk/client-sns";
 import {
   S3Client as S3Client6,
@@ -7790,9 +7798,54 @@ var CustomResourceProvider = class _CustomResourceProvider {
       await this.publishToSns(serviceToken, request);
       return await this.pollS3Response(responseKey, logicalId, operation);
     }
+    await this.waitForBackingLambdaReady(serviceToken, logicalId);
     const response = await this.invokeLambda(serviceToken, request);
     return await this.getCustomResourceResponse(response, responseKey, logicalId, operation);
   }
+  /**
+   * Block until the backing Lambda function for a Custom Resource is in a
+   * state that accepts a synchronous Invoke.
+   *
+   * Two sequential waiters:
+   *   1. `waitUntilFunctionActiveV2` — handles the post-CreateFunction
+   *      `Pending` window (image pull, VPC ENI attachment, layer init).
+   *   2. `waitUntilFunctionUpdatedV2` — handles the post-Update
+   *      `InProgress` window (configuration / code swap settling).
+   * Together they cover the only two transient states that reject
+   * synchronous Invokes.
+   *
+   * In the common case (Lambda has been Active for a while, no in-flight
+   * Update), both waiters return on first poll → ~2 GetFunction calls →
+   * ~200ms overhead. That's the price for correctness; the alternative
+   * (whole-stack Active wait at Lambda CREATE) is ~5–10 minutes per
+   * VPC-attached function.
+   *
+   * `serviceToken` is the Lambda function ARN; the Lambda SDK accepts
+   * both name and ARN as `FunctionName`, so we pass the ARN through
+   * unchanged.
+   *
+   * `maxWaitTime` is set generously (10 min) because VPC ENI attachment
+   * has been observed to take 8+ minutes in pathological cases. The
+   * deploy engine's per-resource `--resource-timeout` (default 30 min)
+   * still bounds the outer Custom Resource provisioning attempt, so
+   * this waiter cap is layered defense, not the only timeout.
+   */
+  async waitForBackingLambdaReady(serviceToken, logicalId) {
+    try {
+      await waitUntilFunctionActiveV2(
+        { client: this.lambdaClient, maxWaitTime: 600 },
+        { FunctionName: serviceToken }
+      );
+      await waitUntilFunctionUpdatedV2(
+        { client: this.lambdaClient, maxWaitTime: 600 },
+        { FunctionName: serviceToken }
+      );
+    } catch (error) {
+      throw new Error(
+        `Lambda backing custom resource ${logicalId} (${serviceToken}) did not reach a ready state for Invoke: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
   /**
    * Publish custom resource request to an SNS topic
    */
@@ -12967,8 +13020,7 @@ import {
   ListFunctionsCommand,
   ListTagsCommand,
   ResourceNotFoundException,
-  waitUntilFunctionActiveV2,
-  waitUntilFunctionUpdatedV2
+  waitUntilFunctionUpdatedV2 as waitUntilFunctionUpdatedV22
 } from "@aws-sdk/client-lambda";
 import {
   DescribeNetworkInterfacesCommand,
@@ -13011,14 +13063,20 @@ var LambdaFunctionProvider = class {
   eniWaitTimeoutMs = 10 * 60 * 1e3;
   eniWaitInitialDelayMs = 1e4;
   eniWaitMaxDelayMs = 3e4;
-  // Budget for the post-CreateFunction / post-Update wait that blocks until
-  // Configuration.State === 'Active' and LastUpdateStatus === 'Successful'.
-  // Must NOT be skipped by --no-wait: downstream resources (Custom Resource
-  // Invokes, EventSourceMappings, etc.) cannot operate against a function
-  // still in Pending / InProgress, so this is required for correctness, not
-  // a "convenience wait" like CloudFront / RDS readiness.
+  // Budget for the post-Update wait that blocks until LastUpdateStatus
+  // === 'Successful'. Required to prevent the SECOND in-flight call (e.g.
+  // UpdateFunctionCode immediately after UpdateFunctionConfiguration)
+  // from racing the first with "function is currently in the following
+  // state: InProgress". Update typically settles in seconds; the 10-min
+  // cap is generous slack for layer-update / VPC-detach edge cases.
   // Seconds (the SDK waiter contract is seconds, not ms).
-  functionReadyMaxWaitSeconds = 10 * 60;
+  //
+  // The post-CreateFunction `State=Active` wait used to live here too
+  // (PR #121) but doubled deploy time on benchmark stacks because every
+  // Lambda paid the cost regardless of whether anything synchronously
+  // invoked it. The Active wait now lives in `CustomResourceProvider`
+  // (the only deploy-time consumer that breaks against Pending).
+  functionUpdateMaxWaitSeconds = 10 * 60;
   // delstack-style ENI cleanup tunables.
   // - initial sleep: gives AWS time to publish post-detach ENI state via
   //   DescribeNetworkInterfaces (right after the update, the API can return
@@ -13087,7 +13145,6 @@ var LambdaFunctionProvider = class {
         Tags: tags
       };
       const response = await this.lambdaClient.send(new CreateFunctionCommand(createParams));
-      await this.waitForFunctionActive(logicalId, resourceType, functionName);
       this.logger.debug(`Successfully created Lambda function ${logicalId}: ${functionName}`);
       return {
         physicalId: response.FunctionName || functionName,
@@ -13097,9 +13154,6 @@ var LambdaFunctionProvider = class {
         }
       };
     } catch (error) {
-      if (error instanceof ProvisioningError) {
-        throw error;
-      }
       const cause = error instanceof Error ? error : void 0;
       throw new ProvisioningError(
         `Failed to create Lambda function ${logicalId}: ${error instanceof Error ? error.message : String(error)}`,
@@ -13355,45 +13409,28 @@ var LambdaFunctionProvider = class {
    * Timeout is a soft warning — downstream Subnet/SG deletion has its own
    * retries.
    */
-  /**
-   * Block until the function's State === 'Active'.
-   *
-   * Used after CreateFunction. Wraps the SDK's built-in
-   * `waitUntilFunctionActiveV2` (acceptors: SUCCESS=Active, FAILURE=Failed,
-   * RETRY=Pending). The waiter throws on FAILURE / TIMEOUT — both surface
-   * as `ProvisioningError` with the function-name as physicalId so the
-   * deploy engine's per-resource error handling treats them identically to
-   * a CreateFunction failure.
-   */
-  async waitForFunctionActive(logicalId, resourceType, functionName) {
-    try {
-      await waitUntilFunctionActiveV2(
-        { client: this.lambdaClient, maxWaitTime: this.functionReadyMaxWaitSeconds },
-        { FunctionName: functionName }
-      );
-    } catch (error) {
-      const cause = error instanceof Error ? error : void 0;
-      throw new ProvisioningError(
-        `Lambda function ${logicalId} did not reach Active state: ${error instanceof Error ? error.message : String(error)}`,
-        resourceType,
-        logicalId,
-        functionName,
-        cause
-      );
-    }
-  }
   /**
    * Block until the function's LastUpdateStatus === 'Successful'.
    *
    * Used after UpdateFunctionConfiguration / UpdateFunctionCode. Wraps the
    * SDK's `waitUntilFunctionUpdatedV2` (acceptors: SUCCESS=Successful,
-   * FAILURE=Failed, RETRY=InProgress). Same error-wrapping contract as
-   * `waitForFunctionActive`.
+   * FAILURE=Failed, RETRY=InProgress). Errors are surfaced as
+   * `ProvisioningError` so the deploy engine's per-resource error
+   * handling treats them identically to an Update API failure.
+   *
+   * NOTE: post-CreateFunction `State=Active` wait was deliberately moved
+   * out of this provider in favor of an on-demand wait inside
+   * `CustomResourceProvider.sendRequest` (the only deploy-time consumer
+   * that breaks against a Pending Lambda). Blocking the entire deploy
+   * DAG behind every Lambda's Active transition more than doubled
+   * deploy time on benchmark stacks; the on-demand wait scoped to the
+   * one resource type that actually needs it preserves the bug fix
+   * without paying the whole-stack tax.
    */
   async waitForFunctionUpdated(logicalId, resourceType, functionName) {
     try {
-      await waitUntilFunctionUpdatedV2(
-        { client: this.lambdaClient, maxWaitTime: this.functionReadyMaxWaitSeconds },
+      await waitUntilFunctionUpdatedV22(
+        { client: this.lambdaClient, maxWaitTime: this.functionUpdateMaxWaitSeconds },
         { FunctionName: functionName }
       );
     } catch (error) {
@@ -16757,6 +16794,11 @@ import {
   DeleteInternetGatewayCommand,
   AttachInternetGatewayCommand,
   DetachInternetGatewayCommand,
+  CreateNatGatewayCommand,
+  DeleteNatGatewayCommand,
+  DescribeNatGatewaysCommand,
+  waitUntilNatGatewayAvailable,
+  waitUntilNatGatewayDeleted,
   CreateRouteTableCommand,
   DeleteRouteTableCommand,
   CreateRouteCommand,
@@ -16802,6 +16844,20 @@ var EC2Provider = class {
     ],
     ["AWS::EC2::InternetGateway", /* @__PURE__ */ new Set(["Tags"])],
     ["AWS::EC2::VPCGatewayAttachment", /* @__PURE__ */ new Set(["VpcId", "InternetGatewayId"])],
+    [
+      "AWS::EC2::NatGateway",
+      /* @__PURE__ */ new Set([
+        "AllocationId",
+        "SubnetId",
+        "ConnectivityType",
+        "PrivateIpAddress",
+        "SecondaryAllocationIds",
+        "SecondaryPrivateIpAddresses",
+        "SecondaryPrivateIpAddressCount",
+        "MaxDrainDurationSeconds",
+        "Tags"
+      ])
+    ],
     ["AWS::EC2::RouteTable", /* @__PURE__ */ new Set(["VpcId", "Tags"])],
     [
       "AWS::EC2::Route",
@@ -16889,6 +16945,8 @@ var EC2Provider = class {
         return this.createInternetGateway(logicalId, resourceType, properties);
       case "AWS::EC2::VPCGatewayAttachment":
         return this.createVpcGatewayAttachment(logicalId, resourceType, properties);
+      case "AWS::EC2::NatGateway":
+        return this.createNatGateway(logicalId, resourceType, properties);
       case "AWS::EC2::RouteTable":
         return this.createRouteTable(logicalId, resourceType, properties);
       case "AWS::EC2::Route":
@@ -16925,6 +16983,8 @@ var EC2Provider = class {
         return this.updateInternetGateway(logicalId, physicalId);
       case "AWS::EC2::VPCGatewayAttachment":
         return this.updateVpcGatewayAttachment(logicalId, physicalId);
+      case "AWS::EC2::NatGateway":
+        return this.updateNatGateway(logicalId, physicalId);
       case "AWS::EC2::RouteTable":
         return this.updateRouteTable(logicalId, physicalId);
       case "AWS::EC2::Route":
@@ -16978,6 +17038,8 @@ var EC2Provider = class {
         return this.deleteInternetGateway(logicalId, physicalId, resourceType, context);
       case "AWS::EC2::VPCGatewayAttachment":
         return this.deleteVpcGatewayAttachment(logicalId, physicalId, resourceType, context);
+      case "AWS::EC2::NatGateway":
+        return this.deleteNatGateway(logicalId, physicalId, resourceType, context);
       case "AWS::EC2::RouteTable":
         return this.deleteRouteTable(logicalId, physicalId, resourceType, context);
       case "AWS::EC2::Route":
@@ -17546,6 +17608,118 @@ var EC2Provider = class {
       );
     }
   }
+  // ─── AWS::EC2::NatGateway ─────────────────────────────────────────
+  //
+  // CloudFormation parity: by default we wait for the new NAT gateway to
+  // reach `available` state before marking the resource created. NAT
+  // provisioning takes ~1–2 minutes (often the longest single step in a
+  // VPC stack). Pass `--no-wait` to skip the wait — `CreateNatGateway`
+  // returns the `NatGatewayId` immediately so dependent Routes /
+  // Subnets that only need the ID can proceed against a still-`pending`
+  // gateway. Anything that requires actual NAT-routed egress (e.g. a
+  // Lambda invocation that hits the internet during deploy) must not
+  // rely on the gateway being live; with `--no-wait`, AWS continues
+  // provisioning asynchronously after the deploy returns.
+  async createNatGateway(logicalId, resourceType, properties) {
+    this.logger.debug(`Creating NatGateway ${logicalId}`);
+    const subnetId = properties["SubnetId"];
+    if (!subnetId) {
+      throw new ProvisioningError(
+        `SubnetId is required for NatGateway ${logicalId}`,
+        resourceType,
+        logicalId
+      );
+    }
+    try {
+      const response = await this.ec2Client.send(
+        new CreateNatGatewayCommand({
+          SubnetId: subnetId,
+          AllocationId: properties["AllocationId"],
+          ConnectivityType: properties["ConnectivityType"] ?? void 0,
+          PrivateIpAddress: properties["PrivateIpAddress"],
+          SecondaryAllocationIds: properties["SecondaryAllocationIds"],
+          SecondaryPrivateIpAddresses: properties["SecondaryPrivateIpAddresses"],
+          SecondaryPrivateIpAddressCount: properties["SecondaryPrivateIpAddressCount"]
+        })
+      );
+      const natGatewayId = response.NatGateway.NatGatewayId;
+      await this.applyTags(natGatewayId, properties, logicalId);
+      if (process.env["CDKD_NO_WAIT"] !== "true") {
+        this.logger.debug(`Waiting for NatGateway ${natGatewayId} to reach available state...`);
+        await waitUntilNatGatewayAvailable(
+          // 15-min cap matches AWS's documented worst case for NAT
+          // provisioning. Per-resource `--resource-timeout` (default
+          // 30 min) still bounds the outer call as a backstop.
+          { client: this.ec2Client, maxWaitTime: 15 * 60 },
+          { NatGatewayIds: [natGatewayId] }
+        );
+        this.logger.debug(`NatGateway ${natGatewayId} is available`);
+      } else {
+        this.logger.debug(
+          `NatGateway ${natGatewayId} created (skipping available-state wait per --no-wait)`
+        );
+      }
+      this.logger.debug(`Successfully created NatGateway ${logicalId}: ${natGatewayId}`);
+      return {
+        physicalId: natGatewayId,
+        attributes: {
+          NatGatewayId: natGatewayId
+        }
+      };
+    } catch (error) {
+      const cause = error instanceof Error ? error : void 0;
+      throw new ProvisioningError(
+        `Failed to create NatGateway ${logicalId}: ${error instanceof Error ? error.message : String(error)}`,
+        resourceType,
+        logicalId,
+        void 0,
+        cause
+      );
+    }
+  }
+  updateNatGateway(logicalId, physicalId) {
+    this.logger.debug(`Updating NatGateway ${logicalId}: ${physicalId} (no-op)`);
+    return Promise.resolve({ physicalId, wasReplaced: false });
+  }
+  async deleteNatGateway(logicalId, physicalId, resourceType, context) {
+    this.logger.debug(`Deleting NatGateway ${logicalId}: ${physicalId}`);
+    try {
+      await this.ec2Client.send(new DeleteNatGatewayCommand({ NatGatewayId: physicalId }));
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        const clientRegion = await this.ec2Client.config.region();
+        assertRegionMatch(
+          clientRegion,
+          context?.expectedRegion,
+          resourceType,
+          logicalId,
+          physicalId
+        );
+        this.logger.debug(`NatGateway ${physicalId} does not exist, skipping deletion`);
+        return;
+      }
+      const cause = error instanceof Error ? error : void 0;
+      throw new ProvisioningError(
+        `Failed to delete NatGateway ${logicalId}: ${error instanceof Error ? error.message : String(error)}`,
+        resourceType,
+        logicalId,
+        physicalId,
+        cause
+      );
+    }
+    this.logger.debug(`Waiting for NatGateway ${physicalId} to reach deleted state...`);
+    try {
+      await waitUntilNatGatewayDeleted(
+        { client: this.ec2Client, maxWaitTime: 15 * 60 },
+        { NatGatewayIds: [physicalId] }
+      );
+    } catch (error) {
+      this.logger.warn(
+        `Wait for NatGateway ${physicalId} deletion did not complete cleanly: ${error instanceof Error ? error.message : String(error)} \u2014 proceeding with downstream delete steps`
+      );
+    }
+    this.logger.debug(`Successfully deleted NatGateway ${logicalId}`);
+  }
   // ─── AWS::EC2::RouteTable ─────────────────────────────────────────
   async createRouteTable(logicalId, resourceType, properties) {
     this.logger.debug(`Creating RouteTable ${logicalId}`);
@@ -18755,6 +18929,15 @@ var EC2Provider = class {
           const sg = resp.SecurityGroups?.[0];
           return sg?.GroupId ? { physicalId: sg.GroupId, attributes: {} } : null;
         }
+        case "AWS::EC2::NatGateway": {
+          const resp = await this.ec2Client.send(
+            new DescribeNatGatewaysCommand({
+              Filter: [{ Name: `tag:${CDK_PATH_TAG}`, Values: [input.cdkPath] }]
+            })
+          );
+          const gw = resp.NatGateways?.find((g) => g.State !== "deleted" && g.State !== "deleting");
+          return gw?.NatGatewayId ? { physicalId: gw.NatGatewayId, attributes: {} } : null;
+        }
         default:
           return null;
       }
@@ -18783,6 +18966,13 @@ var EC2Provider = class {
           );
           return resp.SecurityGroups?.[0] ? { physicalId, attributes: {} } : null;
         }
+        case "AWS::EC2::NatGateway": {
+          const resp = await this.ec2Client.send(
+            new DescribeNatGatewaysCommand({ NatGatewayIds: [physicalId] })
+          );
+          const gw = resp.NatGateways?.find((g) => g.State !== "deleted" && g.State !== "deleting");
+          return gw ? { physicalId, attributes: {} } : null;
+        }
         default:
           return null;
       }
@@ -31106,6 +31296,7 @@ function registerAllProviders(registry) {
   registry.register("AWS::EC2::Subnet", ec2Provider);
   registry.register("AWS::EC2::InternetGateway", ec2Provider);
   registry.register("AWS::EC2::VPCGatewayAttachment", ec2Provider);
+  registry.register("AWS::EC2::NatGateway", ec2Provider);
   registry.register("AWS::EC2::RouteTable", ec2Provider);
   registry.register("AWS::EC2::Route", ec2Provider);
   registry.register("AWS::EC2::SubnetRouteTableAssociation", ec2Provider);
@@ -36139,7 +36330,7 @@ function reorderArgs(argv) {
 }
 async function main() {
   const program = new Command13();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.30.1");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.31.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());