cdkd bootstrap

cdkd bootstrap creates the AWS resources cdkd needs in an account: an S3 bucket for stack state, and per-region storage for the file and container assets your stacks publish. Run it once per account. With --destroy it removes a region's asset storage again.

# state bucket + asset storage for the region
cdkd bootstrap

# asset storage for another region
cdkd bootstrap --region us-west-2

# state bucket only
cdkd bootstrap --no-assets

# a custom asset bucket name
cdkd bootstrap --asset-bucket my-org-cdkd-assets

# remove that region's asset storage
cdkd bootstrap --destroy --region us-west-2

You do not have to bootstrap every region by hand. The first cdkd deploy into a region creates its asset storage.

Options

The region is the first of --region, AWS_REGION, AWS_DEFAULT_REGION, your profile's region and us-east-1. Name it explicitly. The region decides which marker cdkd writes, so a bootstrap that lands in the wrong region opts that region in. Region resolution has the full rules.

What bootstrap creates

cdkd configures them as follows:

• The state bucket is versioned, encrypted with AES-256, and has a bucket policy that admits this account only.
• The state bucket has a lifecycle rule, cdkd-custom-resource-responses-expiration, for objects under custom-resource-responses/cdkd-1. A custom resource's handler writes its response there, Data included. cdkd deletes each response once it has read it, so the rule only removes responses left behind by an interrupted run. The current version expires after one day, and the version that leaves behind is deleted one day later. S3 rounds each step up to the next midnight UTC.
• The asset bucket is encrypted with AES-256 and has the same account-only policy. It is not versioned.
• The ECR repository has immutable tags.

The bootstrap marker is a small file in the state bucket that records the names of a region's asset bucket and ECR repository. A region that has a marker is opted in to cdkd-owned asset storage. cdkd writes the marker last, so a crash partway through a bootstrap leaves the region not opted in.

To see which regions are opted in, run cdkd state info. It reports them on its Asset storage: line, or in the assetStorage field of its JSON output.

Asset destinations after opt-in (cdkd-assets mode)

Whether a region has a marker decides where a deploy publishes its assets.

In legacy mode, a deploy prints a one-line notice that names the region and cdk gc.

What cdkd redirects in cdkd-assets mode

A CDK app writes its asset destinations into its asset manifest, and by default they are the CDK bootstrap bucket and repository. In cdkd-assets mode, cdkd redirects those default destinations for this account and region: cdk-<qualifier>-assets-... and cdk-<qualifier>-container-assets-....

cdkd also rewrites the references to them in the template, so that resources point at the storage the assets went to. Examples are Code.S3Bucket, Code.ImageUri, s3.Asset URLs in environment variables, and a nested stack's TemplateURL. The object key and the image tag are content hashes, and they do not change.

cdkd never redirects storage you chose yourself. That covers a custom fileAssetsBucketName or imageAssetsRepositoryName, the staging buckets of AppStagingSynthesizer, and destinations in another region.

What each command does in cdkd-assets mode

• deploy redirects publishes and rewrites templates, nested stacks included. It fails any resource whose resolved properties still name CDK bootstrap storage.
• diff, with or without --recursive, rewrites the template, so that the plan matches what deploy will do.
• import rewrites the template, but records the original references in state.
• publish-assets redirects. When no state bucket resolves, it falls back to legacy mode and prints an info line.
• synth and export do not rewrite. synth prints the app's template, and export returns the stack to CloudFormation.
• destroy, state, drift and events work from state and are unchanged.

The first deploy after a region opts in

The first deploy after a region opts in updates every resource that has an asset. It is an ordinary in-place update that points Code or Image at cdkd storage. The content is the same and nothing is replaced.

The first deploy after a cdkd import shows the same update, because import recorded the original references.

Keeping CDK bootstrap destinations

--use-cdk-bootstrap-assets publishes to the CDK bootstrap destinations for one run, even when the region is opted in. It also suppresses the legacy-mode notice. deploy, diff, import and publish-assets accept it. Use it for an app that is deployed through both CloudFormation and cdkd during a migration.

cdkd deploy MyStack --use-cdk-bootstrap-assets

To set it for an app, put this in cdk.json:

{
  "context": {
    "cdkd": { "useCdkBootstrapAssets": true }
  }
}

Why cdkd owns its asset storage

cdk gc decides which assets are in use by scanning CloudFormation stack templates. A stack that cdkd deployed has no CloudFormation stack. Its assets in the CDK bootstrap bucket therefore look unreferenced to cdk gc, and cdk gc deletes them.

Storage that cdkd owns is out of cdk gc's reach, and cdkd gc collects it by reading cdkd's own state files. The asset-storage design note has the full reasoning.

Auto-create on first deploy

When cdkd deploy runs in a region that has no marker, it offers to create the asset bucket, the ECR repository and the marker, the same way cdkd bootstrap does.

To opt out, pass --no-auto-asset-storage, or set context.cdkd.autoAssetStorage: false in cdk.json.

Only deploy creates storage. diff, import and publish-assets never create resources. Auto-create always uses the default names, so custom names need an explicit cdkd bootstrap.

Custom asset-storage names

--asset-bucket and --container-repo replace the default names.

cdkd bootstrap --region us-west-2 \
  --asset-bucket my-org-cdkd-assets-usw2 \
  --container-repo my-org/cdkd-container-assets

There are two reasons to use them. An organization's naming policy may require a particular shape. And S3 bucket names are global, so another account can take the predictable default name before you do.

cdkd validates the names before any AWS call:

cdkd writes the names into the region's marker, and every command reads them from the marker afterwards. Three things follow from that:

• Running cdkd bootstrap again with no name flags keeps the names in the marker.
• Bootstrapping again with names that differ from the marker is refused with ASSET_STORAGE_NAME_CONFLICT. Run cdkd bootstrap --destroy for the region first.
• Passing a name flag with --no-assets or --destroy is refused. Teardown reads the names from the marker.

Edge cases

• The asset bucket name is owned by another account. cdkd refuses. Every S3 call on the asset bucket also passes ExpectedBucketOwner.
• The bucket is yours but in another region. cdkd refuses with ASSET_STORAGE_FOREIGN_REGION_BUCKET, and --force does not override it. You can reach this by bootstrapping two regions under one custom bucket name, because a custom name carries no region.
• The asset bucket or repository was deleted while the marker exists. Deploys fail with a hint to bootstrap again. cdkd does not fall back to CDK bootstrap storage.
• The marker names a bucket or repository that the rules above reject. cdkd treats such a marker as malformed. Running cdkd bootstrap again warns, says what the marker recorded, and rewrites it with the default names. Every other command refuses the marker.

Re-running bootstrap

Running cdkd bootstrap again is safe. Without --force, it leaves existing resources untouched and creates what is missing. That makes it the way to add asset storage for a new region to an account that is already bootstrapped.

With --force, it reconfigures existing resources: it applies encryption, the bucket policy, the lifecycle rule and ECR tag immutability again.

cdkd adds the lifecycle rule to the state bucket's existing lifecycle configuration. It keeps every rule already there, and it adds nothing when a rule with its ID exists. A state bucket bootstrapped before the rule existed gets it from the first deploy or destroy that runs a custom resource, at most once per run. Adding the rule needs s3:GetLifecycleConfiguration, s3:PutLifecycleConfiguration and s3:ListBucket on the state bucket. Without them, cdkd prints a warning, leaves the configuration unchanged, and carries on.

Do not use --state-prefix custom-resource-responses. The rule would expire the state of a stack whose name starts with cdkd-1 under that prefix. cdkd does not add the rule while such a state exists, and it warns instead. It checks only when it adds the rule, so a stack created after that is not checked.

An account that was bootstrapped by an older cdkd needs no manual step. The first deploy into each region creates the storage. Upgrading or downgrading the binary is safe in either mode, because older binaries ignore the marker, and both storages hold the same content-addressed objects.

Teardown (cdkd bootstrap --destroy)

cdkd bootstrap --destroy removes one region's asset storage: the asset bucket, the ECR repository and the marker. It asks for confirmation first, and it refuses while a deployed stack still uses the storage.

cdkd bootstrap --destroy --region us-west-2          # asks for confirmation
cdkd bootstrap --destroy --region us-west-2 --yes    # no prompt (CI)

Tearing down asset storage describes the steps, the checks, and how to delete the state bucket as well.

Relationship with cdk bootstrap

cdkd does not need cdk bootstrap. It deploys with the caller's credentials and does not use CDK's bootstrap roles. It also does not resolve the template's BootstrapVersion parameter. A region that cdk bootstrap never touched therefore works.

One exception: for a cross-account reference that CDK generates for you, cdkd reads the producer's outputs through the producer account's CDK lookup role, so both accounts need cdk bootstrap, the producer's with --trust-for-lookup <consumer-account>. Reading from another account has the details.

After cdkd export hands a stack back to CloudFormation, cdk bootstrap is the CDK CLI's own prerequisite again.

Exit codes

Exit codes has the table for every command.

Related

• Getting Started: where bootstrap fits in a first run
• Tearing down asset storage: --destroy in full
• cdkd gc: collecting the storage this command creates
• cdkd publish-assets: publishing assets without deploying
• State Store: what the state bucket holds