@go-to-k/cdkd 0.32.0 → 0.34.0

package/README.md

@@ -25,7 +25,7 @@
 - **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 / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
-- **`--aggressive-vpc-parallel`**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks)
+- **VPC route DependsOn relaxation (on by default)**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks). Pass `--no-aggressive-vpc-parallel` to opt out.
 
 > **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.
 
@@ -175,7 +175,7 @@ the full per-type table.
 
 - **Node.js** >= 20.0.0
 - **AWS CDK Bootstrap**: You must run `cdk bootstrap` before using cdkd. cdkd uses CDK's bootstrap bucket (`cdk-hnb659fds-assets-*`) for asset uploads (Lambda code, Docker images). Custom bootstrap qualifiers are supported — CDK embeds the correct bucket/repo names in the asset manifest during synthesis.
-- **AWS Credentials**: Configured via environment variables, `~/.aws/credentials`, or `--profile` option
+- **AWS Credentials**: Configured via environment variables, `~/.aws/credentials`, `--profile`, or `--role-arn` option. **The credentials must have admin-equivalent permissions for the resources being deployed.** Unlike `cdk deploy`, cdkd does NOT route through CloudFormation, so there is no cfn-exec-role to delegate to — every IAM / EC2 / Lambda / etc. API call is issued from cdkd directly. CDK CLI's `cdk-hnb659fds-deploy-role-*` only carries CFn + asset-publish permissions and is therefore NOT sufficient for cdkd. See `--role-arn` in [docs/cli-reference.md](docs/cli-reference.md) for assuming a role with the right permissions.
 
 ## Installation
 
@@ -406,7 +406,7 @@ ElastiCache) don't apply to destroy either — their providers are
 already non-blocking on delete because they're leaves in the destroy
 DAG.
 
-## `--aggressive-vpc-parallel`: relax CDK-defensive VPC route DependsOn
+## VPC route DependsOn relaxation (on by default)
 
 CDK synth eagerly injects `DependsOn` from VPC Lambdas (and adjacent
 IAM Role / Policy / Lambda::Url / EventSourceMapping resources) onto
@@ -418,35 +418,35 @@ route), but it is NOT required at *deploy time* — `CreateFunction` /
 `CreateFunctionUrlConfig` / `AddPermission` /
 `CreateEventSourceMapping` all accept a function in `Pending` state.
 
-For VPC + Lambda + CloudFront stacks this turns into a serial
-critical path:
+For VPC + Lambda + CloudFront stacks the strict-CDK-ordering chain is serial:
 
 ```text
 NAT GW (~2-3 min) → DefaultRoute → Lambda → Lambda::Url → Distribution propagation (~3 min)
 ```
 
-Pass `--aggressive-vpc-parallel` to drop the route DependsOn so
-Distribution + Lambda::Url dispatch right after IAM Role / Subnet are
-ready and propagate in parallel with NAT stabilization:
+cdkd drops the route DependsOn by default so Distribution + Lambda::Url
+dispatch right after IAM Role / Subnet are ready and propagate in
+parallel with NAT stabilization:
+
+| Mode | Critical path | Total |
+| --- | --- | --- |
+| `--no-aggressive-vpc-parallel` (opt-out) | NAT → Lambda → CF (serial) | ~6 min |
+| **default** | max(NAT, CF) | **~3 min** |
+
+Measured **−54.6%** on `tests/integration/bench-cdk-sample` (398.59s
+with `--no-aggressive-vpc-parallel` → 181.03s default).
+
+To opt out (e.g. for a stack with a Custom Resource that synchronously
+invokes a VPC Lambda outside cdkd's Lambda-ServiceToken Active wait):
 
 ```bash
-cdkd deploy --aggressive-vpc-parallel
+cdkd deploy --no-aggressive-vpc-parallel
 ```
 
-| Mode | Critical path | Total |
-| --- | --- | --- |
-| Default | NAT → Lambda → CF (serial) | ~6 min |
-| `--aggressive-vpc-parallel` | max(NAT, CF) | ~3 min |
-
-Measured **−45.6%** on `tests/integration/bench-cdk-sample` (387s
-baseline → 211s relaxed).
-
-Off by default for v1: opt-in is the conservative play because
-CloudFront `Create` / `Delete` are each ~5 min, so a Lambda-side
-async failure incurs a high rollback cost. Deploy-only —
-`cdkd destroy` doesn't accept it (the route DependsOn doesn't
-constrain delete-time correctness; Lambda hyperplane ENI release
-is the actual destroy bottleneck).
+Deploy-only — the relaxation has no effect on destroy ordering (the
+route DependsOn doesn't constrain delete-time correctness; Lambda
+hyperplane ENI release is the actual destroy bottleneck and is handled
+separately by `lambda-vpc-deps.ts`).
 
 See [docs/cli-reference.md](docs/cli-reference.md) for the full
 type-pair allowlist, implementation pointers, and trade-off notes.

package/dist/cli.js

@@ -477,6 +477,10 @@ function parseContextOptions(contextArgs) {
 var commonOptions = [
   new Option("--verbose", "Enable verbose logging").default(false),
   new Option("--profile <profile>", "AWS profile"),
+  new Option(
+    "--role-arn <arn>",
+    "IAM role ARN to assume for AWS API calls (env: CDKD_ROLE_ARN); the role MUST have admin-equivalent permissions because cdkd issues raw service API calls and does not route through CloudFormation, so CDK CLI deploy-roles will NOT work"
+  ),
   new Option(
     "-y, --yes",
     "Automatically answer interactive prompts with the recommended response (e.g. confirm destroy)"
@@ -611,9 +615,9 @@ var noWaitOption = new Option(
   "Skip waiting for async resources to stabilize (CloudFront, RDS, ElastiCache, NAT Gateway)"
 );
 var aggressiveVpcParallelOption = new Option(
-  "--aggressive-vpc-parallel",
-  "Relax CDK-injected VPC route DependsOn to let CloudFront/Lambda::Url create in parallel with NAT GW stabilization"
-).default(false);
+  "--no-aggressive-vpc-parallel",
+  "Disable the default relaxation of CDK-injected VPC route DependsOn (on by default; opt out to keep the strict CDK ordering)"
+);
 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)),
@@ -1256,6 +1260,41 @@ function normalizeAwsError(err, context = {}) {
 // src/cli/commands/bootstrap.ts
 init_aws_clients();
 
+// src/utils/role-arn.ts
+import { STSClient as STSClient2, AssumeRoleCommand } from "@aws-sdk/client-sts";
+async function applyRoleArnIfSet(opts) {
+  const roleArn = opts.roleArn || process.env["CDKD_ROLE_ARN"];
+  if (!roleArn)
+    return;
+  const logger = getLogger().child("role-arn");
+  logger.debug(`Assuming role ${roleArn}...`);
+  const sts = new STSClient2({ ...opts.region && { region: opts.region } });
+  try {
+    const response = await sts.send(
+      new AssumeRoleCommand({
+        RoleArn: roleArn,
+        RoleSessionName: `cdkd-${Date.now()}`,
+        DurationSeconds: 3600
+      })
+    );
+    if (!response.Credentials) {
+      throw new Error(`AssumeRole returned no credentials for role ${roleArn}`);
+    }
+    const { AccessKeyId, SecretAccessKey, SessionToken, Expiration } = response.Credentials;
+    if (!AccessKeyId || !SecretAccessKey || !SessionToken) {
+      throw new Error(`AssumeRole response missing credentials fields for role ${roleArn}`);
+    }
+    process.env["AWS_ACCESS_KEY_ID"] = AccessKeyId;
+    process.env["AWS_SECRET_ACCESS_KEY"] = SecretAccessKey;
+    process.env["AWS_SESSION_TOKEN"] = SessionToken;
+    logger.info(
+      `Assumed role ${roleArn} (session expires ${Expiration?.toISOString() ?? "unknown"})`
+    );
+  } finally {
+    sts.destroy();
+  }
+}
+
 // src/cli/config-loader.ts
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
@@ -1409,6 +1448,7 @@ async function bootstrapCommand(options) {
   }
   logger.info("Starting cdkd bootstrap...");
   logger.debug("Options:", options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const awsClients = new AwsClients({
     ...options.region && { region: options.region },
     ...options.profile && { profile: options.profile }
@@ -1553,7 +1593,7 @@ import { join as join4 } from "path";
 // src/synthesis/synthesizer.ts
 import { existsSync as existsSync3, mkdirSync, statSync } from "node:fs";
 import { resolve as resolve3 } from "node:path";
-import { GetCallerIdentityCommand as GetCallerIdentityCommand2, STSClient as STSClient2 } from "@aws-sdk/client-sts";
+import { GetCallerIdentityCommand as GetCallerIdentityCommand2, STSClient as STSClient3 } from "@aws-sdk/client-sts";
 
 // src/synthesis/app-executor.ts
 import { spawn } from "node:child_process";
@@ -2744,7 +2784,7 @@ var Synthesizer = class {
     const region = options.region || process.env["AWS_REGION"] || process.env["AWS_DEFAULT_REGION"];
     let accountId;
     try {
-      const stsClient = new STSClient2({ ...region && { region } });
+      const stsClient = new STSClient3({ ...region && { region } });
       const identity = await stsClient.send(new GetCallerIdentityCommand2({}));
       accountId = identity.Account;
       stsClient.destroy();
@@ -2876,6 +2916,7 @@ async function synthCommand(options) {
     logger.setLevel("debug");
   }
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const app = resolveApp(options.app);
   if (!app) {
     throw new Error(
@@ -3007,6 +3048,7 @@ async function listCommand(patterns, options) {
     logger.setLevel("debug");
   }
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const app = resolveApp(options.app);
   if (!app) {
     throw new Error(
@@ -3597,8 +3639,8 @@ var AssetPublisher = class {
       const region = options.region || process.env["AWS_REGION"] || "us-east-1";
       let accountId = options.accountId;
       if (!accountId) {
-        const { STSClient: STSClient9, GetCallerIdentityCommand: GetCallerIdentityCommand11 } = await import("@aws-sdk/client-sts");
-        const stsClient = new STSClient9({ region });
+        const { STSClient: STSClient10, GetCallerIdentityCommand: GetCallerIdentityCommand11 } = await import("@aws-sdk/client-sts");
+        const stsClient = new STSClient10({ region });
         const identity = await stsClient.send(new GetCallerIdentityCommand11({}));
         accountId = identity.Account;
         stsClient.destroy();
@@ -4800,7 +4842,7 @@ var DagBuilder = class {
         if (skip?.has(depId)) {
           relaxedEdgeCount++;
           this.logger.debug(
-            `Skipped CDK-defensive DependsOn edge: ${depId} -> ${logicalId} (--aggressive-vpc-parallel)`
+            `Skipped CDK-defensive DependsOn edge: ${depId} -> ${logicalId} (default; opt out with --no-aggressive-vpc-parallel)`
           );
           continue;
         }
@@ -4817,7 +4859,7 @@ var DagBuilder = class {
     }
     if (relaxedEdgeCount > 0) {
       this.logger.info(
-        `[DagBuilder] Relaxed ${relaxedEdgeCount} CDK-defensive DependsOn edge(s) (--aggressive-vpc-parallel)`
+        `[DagBuilder] Relaxed ${relaxedEdgeCount} CDK-defensive DependsOn edge(s) (default; opt out with --no-aggressive-vpc-parallel)`
       );
     }
     this.logger.debug(`Dependency graph built: ${resourceIds.length} nodes, ${edgeCount} edges`);
@@ -25556,7 +25598,7 @@ import {
   ModifyCacheClusterCommand,
   ListTagsForResourceCommand as ListTagsForResourceCommand14
 } from "@aws-sdk/client-elasticache";
-import { STSClient as STSClient5, GetCallerIdentityCommand as GetCallerIdentityCommand6 } from "@aws-sdk/client-sts";
+import { STSClient as STSClient6, GetCallerIdentityCommand as GetCallerIdentityCommand6 } from "@aws-sdk/client-sts";
 var ElastiCacheProvider = class {
   client;
   stsClient;
@@ -26079,7 +26121,7 @@ var ElastiCacheProvider = class {
     if (this.cachedAccountId)
       return this.cachedAccountId;
     if (!this.stsClient) {
-      this.stsClient = new STSClient5(this.providerRegion ? { region: this.providerRegion } : {});
+      this.stsClient = new STSClient6(this.providerRegion ? { region: this.providerRegion } : {});
     }
     const identity = await this.stsClient.send(new GetCallerIdentityCommand6({}));
     if (!identity.Account) {
@@ -26106,7 +26148,7 @@ import {
   NamespaceNotFound,
   ServiceNotFound
 } from "@aws-sdk/client-servicediscovery";
-import { STSClient as STSClient6, GetCallerIdentityCommand as GetCallerIdentityCommand7 } from "@aws-sdk/client-sts";
+import { STSClient as STSClient7, GetCallerIdentityCommand as GetCallerIdentityCommand7 } from "@aws-sdk/client-sts";
 var ServiceDiscoveryProvider = class {
   client;
   stsClient;
@@ -26138,7 +26180,7 @@ var ServiceDiscoveryProvider = class {
   }
   getStsClient() {
     if (!this.stsClient) {
-      this.stsClient = new STSClient6(this.providerRegion ? { region: this.providerRegion } : {});
+      this.stsClient = new STSClient7(this.providerRegion ? { region: this.providerRegion } : {});
     }
     return this.stsClient;
   }
@@ -27121,7 +27163,7 @@ import {
   GetTagsCommand,
   EntityNotFoundException
 } from "@aws-sdk/client-glue";
-import { STSClient as STSClient7, GetCallerIdentityCommand as GetCallerIdentityCommand8 } from "@aws-sdk/client-sts";
+import { STSClient as STSClient8, GetCallerIdentityCommand as GetCallerIdentityCommand8 } from "@aws-sdk/client-sts";
 var GlueProvider = class {
   client;
   stsClient;
@@ -27648,7 +27690,7 @@ var GlueProvider = class {
     if (this.cachedAccountId)
       return this.cachedAccountId;
     if (!this.stsClient) {
-      this.stsClient = new STSClient7(this.providerRegion ? { region: this.providerRegion } : {});
+      this.stsClient = new STSClient8(this.providerRegion ? { region: this.providerRegion } : {});
     }
     const identity = await this.stsClient.send(new GetCallerIdentityCommand8({}));
     if (!identity.Account) {
@@ -32919,6 +32961,7 @@ async function deployCommand(stacks, options) {
     ...options.resourceWarnAfter && { resourceWarnAfter: options.resourceWarnAfter },
     ...options.resourceTimeout && { resourceTimeout: options.resourceTimeout }
   });
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   if (!options.wait) {
     process.env["CDKD_NO_WAIT"] = "true";
   }
@@ -33020,8 +33063,8 @@ async function deployCommand(stacks, options) {
         addDependencies(stack.stackName);
       }
     }
-    const { STSClient: STSClient9, GetCallerIdentityCommand: GetCallerIdentityCommand11 } = await import("@aws-sdk/client-sts");
-    const stsClient = new STSClient9({
+    const { STSClient: STSClient10, GetCallerIdentityCommand: GetCallerIdentityCommand11 } = await import("@aws-sdk/client-sts");
+    const stsClient = new STSClient10({
       region: options.region || process.env["AWS_REGION"] || "us-east-1"
     });
     const callerIdentity = await stsClient.send(new GetCallerIdentityCommand11({}));
@@ -33265,6 +33308,7 @@ async function diffCommand(stacks, options) {
     logger.setLevel("debug");
   }
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const app = resolveApp(options.app);
   if (!app) {
     throw new Error(
@@ -33677,6 +33721,7 @@ async function destroyCommand(stackArgs, options) {
     ...options.resourceWarnAfter && { resourceWarnAfter: options.resourceWarnAfter },
     ...options.resourceTimeout && { resourceTimeout: options.resourceTimeout }
   });
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const region = options.region || process.env["AWS_REGION"] || "us-east-1";
   const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
   logger.info("Starting stack destruction...");
@@ -34278,6 +34323,7 @@ async function orphanCommand(pathArgs, options) {
   if (options.verbose)
     logger.setLevel("debug");
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   if (pathArgs.length === 0) {
     throw new Error(
       "'cdkd orphan' requires at least one construct path, e.g. 'cdkd orphan MyStack/MyTable'.\n       To remove a stack's state record (the previous behavior), use:\n         cdkd state orphan MyStack"
@@ -34567,6 +34613,7 @@ async function publishAssetsCommand(options) {
     logger.setLevel("debug");
   }
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   logger.info("Publishing assets...");
   logger.debug("Asset manifest path:", options.path);
   const publisher = new AssetPublisher();
@@ -34601,6 +34648,7 @@ async function forceUnlockCommand(stackArgs, options) {
     logger.setLevel("debug");
   }
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const stackPatterns = stackArgs.length > 0 ? stackArgs : options.stack ? [options.stack] : [];
   if (stackPatterns.length === 0) {
     throw new Error("Stack name is required. Usage: cdkd force-unlock <stack-name>");
@@ -34696,6 +34744,7 @@ async function stateMigrateCommand(options) {
   const logger = getLogger();
   if (options.verbose)
     logger.setLevel("debug");
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const region = options.region || process.env["AWS_REGION"] || "us-east-1";
   const awsClients = new AwsClients({
     region,
@@ -35009,6 +35058,7 @@ function resolveSingleRegion(stackName, refs, requestedRegion) {
 }
 async function setupStateBackend(options) {
   warnIfDeprecatedRegion(options);
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const awsClients = new AwsClients({
     ...options.region && { region: options.region },
     ...options.profile && { profile: options.profile }
@@ -35624,6 +35674,7 @@ async function stateInfoCommand(options) {
   const logger = getLogger();
   if (options.verbose)
     logger.setLevel("debug");
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const awsClients = new AwsClients({
     ...options.region && { region: options.region },
     ...options.profile && { profile: options.profile }
@@ -35916,6 +35967,7 @@ async function importCommand(stackArg, options) {
     logger.setLevel("debug");
     process.env["CDKD_NO_LIVE"] = "1";
   }
+  await applyRoleArnIfSet({ roleArn: options.roleArn, region: options.region });
   const region = options.region || process.env["AWS_REGION"] || "us-east-1";
   const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
   if (options.region) {
@@ -36436,7 +36488,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.32.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.34.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());