Skip to content
cdkd

Getting Started

cdkd works with your existing CDK app as-is — install it, run cdkd bootstrap once per AWS account, and replace cdk deploy with cdkd deploy.

Installation

npm i -g @go-to-k/cdkd          # latest release
npm i -g @go-to-k/cdkd@0.0.2    # pin to a specific version

The installed binary is cdkd.

Quick Start

First-time setup: run cdkd bootstrap once per AWS account before any other command; it replaces cdk bootstrap, which cdkd does not require (details in Prerequisites).

# Bootstrap (creates S3 state bucket + asset storage — one-time setup per AWS account)
cdkd bootstrap

# List stacks in the CDK app
cdkd list

# Deploy your CDK app
cdkd deploy

# Deploy at maximum speed: skip slow stabilization waits
cdkd deploy --no-wait

# Check what would change
cdkd diff

# Tear down
cdkd destroy

Prerequisites

  • Node.js >= 20.0.0
  • AWS credentials with admin-equivalent permissions for the resources being deployed. cdkd does NOT route through CloudFormation, so CDK CLI's cdk-hnb659fds-deploy-role-* is NOT sufficient — see --role-arn.

AWS CDK's cdk bootstrap is not required. Instead, run cdkd bootstrap once per account: it creates the S3 state bucket (cdkd-state-{accountId}) that cdkd uses to track deployed resources, plus cdkd-owned asset storage (by default a cdkd-assets-{accountId}-{region} bucket + a cdkd-container-assets-{accountId}-{region} ECR repo; custom names via --asset-bucket / --container-repo, skip with --no-assets; see cdkd bootstrap). Per-region asset storage is added automatically on the first cdkd deploy into each region. Existing setups, legacy-mode opt-outs, and how this relates to cdk bootstrap: see Upgrading from an earlier cdkd version.

Upgrading from an earlier cdkd version

No breaking change, no manual step: just deploy. The first cdkd deploy into each region auto-creates the cdkd-owned asset storage (interactive runs are asked once per region, --yes / CI runs create it automatically) and shows a one-time in-place UPDATE repointing asset references — content identical, no replacement. Downgrading is safe too (older binaries ignore the marker). If you bootstrapped under a previous cdkd version, the legacy region-suffixed state bucket name (cdkd-state-{accountId}-{region}) is still picked up automatically with a deprecation warning. Explicit pre-provisioning (cdkd bootstrap --region <r>), legacy-mode opt-outs, and how this relates to cdk bootstrap: see cdkd bootstrap.

Usage

cdkd has three command families:

  • Top-level commands (cdkd deploy / destroy / diff / synth / list / import / orphan / publish-assets) require a CDK app — they synthesize a template to learn what they're operating on.
  • cdkd state ... subcommands (state info / list / resources / show / orphan / destroy / migrate / refresh-observed) operate on the S3 state bucket only and do NOT need the CDK app — use them to inspect / clean up state when the source is gone or you don't want to synth. cdkd state destroy is the CDK-app-free counterpart of cdkd destroy.
  • cdkd local ... subcommands (local invoke / start-api / run-task / start-service) run synthesized workloads locally inside Docker containers — no AWS deploy needed. Modeled on sam local * but reads CDK state directly via --from-state (cdkd-managed) or --from-cfn-stack (CFn-managed). See Local execution.

Options like --app, --state-bucket, and --context can be omitted if configured via cdk.json or environment variables (CDKD_APP, CDKD_STATE_BUCKET).

# Synth + deploy
cdkd synth
cdkd deploy                         # single-stack auto-detected
cdkd deploy MyStack                 # by name (or 'MyStage/Api' display path)
cdkd deploy --all
cdkd deploy --dry-run               # plan only, no changes
cdkd deploy --no-rollback           # Terraform-style: keep partial state on failure
cdkd rollback MyStack               # revert a failed --no-rollback / interrupted deploy
cdkd deploy --no-wait               # skip multi-minute waits (RDS / ElastiCache / NAT)
cdkd deploy --full-wait             # also wait where cdkd's default does not (ECS steady state, CloudFront Deployed)

# Inspect what would change
cdkd diff MyStack
cdkd diff MyStack --fail            # exit 1 on any change (CI gate)

# Drift detection — compare state vs AWS reality (no synth)
cdkd drift MyStack                  # exit 1 if drift
cdkd drift MyStack --accept --yes   # state ← AWS
cdkd drift MyStack --revert --yes   # AWS ← state

# State secret hygiene — clean + audit. Keeps cdkd state free of sensitive
# plaintext: a resolved secret dynamic reference is stored as its
# {{resolve:...}} expression. No deploy, no AWS mutation.
cdkd scrub MyStack                  # clean existing state in place
cdkd scrub MyStack --dry-run        # audit only, report what would change
cdkd scrub MyStack --dry-run --fail # standing CI gate: exit 1 if plaintext remains

# Asset / destroy / unlock
cdkd publish-assets                 # synth + upload only (typical CI split)
cdkd destroy MyStack
cdkd orphan MyStack/MyBucket        # drop one resource from state (AWS resource stays)
cdkd force-unlock MyStack           # clear stale lock from an interrupted deploy / cancelled CI job
cdkd gc --dry-run                   # reclaim unreferenced cdkd-owned assets (S3 + ECR)

# Migrate between cdkd and CloudFormation
cdkd import MyStack --yes           # adopt existing AWS resources into cdkd state
cdkd export MyStack                 # hand a cdkd-managed stack back to CloudFormation

# State-bucket-only commands (no CDK app needed)
cdkd state info                     # bucket name, region, schema version
cdkd state list                     # one row per (stackName, region)
cdkd state list --tree              # parent → child nested-stack tree
cdkd state show MyStack             # full state record
cdkd state resources MyStack        # logical id / type / physical id
cdkd state destroy MyStack          # delete AWS resources + state, no CDK app
cdkd state orphan MyStack           # remove state record only (AWS resources stay)

See the CLI reference for the full flag matrix (--concurrency, --no-aggressive-vpc-parallel, --allow-unsupported-properties, --role-arn, etc.), per-command details including the synth-driven per-resource cdkd orphan <constructPath> variant, and stage / wildcard pattern matching.

Next steps

Last updated:

Released under the Apache-2.0 License.

Copyright © go-to-k