Import options and the import plan

This page is the reference for cdkd import: its flags, the plan it prints, and the details of a CloudFormation migration. For the walkthroughs, start at Importing Existing Resources.

# print the plan, write nothing
cdkd import MyStack --dry-run

# import one resource
cdkd import MyStack --resource Uploads5E5E9B2F=acme-uploads

# that id, and look up the rest
cdkd import MyStack --resource Uploads5E5E9B2F=acme-uploads --auto

# rebuild existing state, no prompt
cdkd import MyStack --force --yes

Options

cdkd import also takes the common --app, --output, --context, --state-bucket, --state-prefix, --profile, --role-arn and --verbose options described in the CLI Reference.

A prompt that is reached without a terminal does not hang. It fails with NON_INTERACTIVE_CONFIRM and exit code 1, which is why CI needs --yes.

Which resources a run imports

The flags you pass decide whether cdkd imports only what you name, or everything it can find.

The three cases also treat existing state differently. Listing resources without --auto adds them to the state that is already there. The other two cases rebuild every record from the template, which is why they need --force when state exists.

--force

--force is needed only when the import would drop or overwrite a record that is already in state.

A damaged record blocks an import that adds resources

When you list resources without --auto, cdkd copies every record you did not list into the new state unchanged. It refuses to do that when one of those records is not a valid resource record: a null, a string, or an object with no resourceType. The refusal names the damaged records and exits 1 with STATE_RESOURCES_MALFORMED.

To repair one, list it, so that cdkd replaces it with what AWS reports:

cdkd import MyStack --resource <logicalId>=<physicalId> --force

If the import of that resource fails, cdkd refuses again before saving. An import of everything and --migrate-from-cloudformation rebuild all records and are not refused. State Management describes how other commands treat a damaged record.

Read the import plan

Every run prints one row per template resource and a summary, then asks before it writes state:

Import plan:
  ✓ Uploads5E5E9B2F (AWS::S3::Bucket) (acme-uploads)
  - ResizeFn9A1B2C3D (AWS::Lambda::Function) — not in --resource / --resource-mapping (use --auto to include)

Summary: 1 imported, 0 not found, 0 unsupported, 1 out of scope, 0 failed

An import is not all-or-nothing. After you confirm, cdkd writes state for the rows marked ✓ and leaves the others out. When no row is marked ✓, cdkd writes no state.

How the lookups can fall short

How cdkd finds each resource describes the two lookups: by the name the template sets, then in a CloudFormation stack of the same name. This section covers when each one does not find a resource. In every case, --resource names the resource directly.

The CloudFormation lookup is skipped or fails

The CloudFormation lookup is skipped when no CloudFormation stack has the cdkd stack's name. When the call fails, for example because cloudformation:DescribeStackResources is denied or throttled, cdkd warns and continues with the name lookup alone.

cdkd assumes a CloudFormation stack with the same name belongs to the same application, and prints the name of the stack it read from.

Names built from the account or region

A name such as `app-${this.account}` is not a plain string in the template. On a stack with no fixed account, it synthesizes to an Fn::Join or Fn::Sub over AWS::AccountId. cdkd works such a name out before it looks the resource up, as long as the name is built only from:

• string literals,
• Fn::Join and Fn::Sub,
• the pseudo-parameters AWS::AccountId, AWS::Region, AWS::Partition and AWS::URLSuffix.

A name that uses anything else stays unresolved: a Ref to a resource or parameter, Fn::GetAtt, Fn::Select, AWS::StackName, or a {{resolve:...}} reference. The CloudFormation lookup or --resource then has to supply that resource.

cdkd takes the account from sts:GetCallerIdentity. It takes the region from the stack's env.region. A stack with no fixed region uses AWS_REGION, then us-east-1; the deprecated --region flag, when passed, takes precedence over both. Your profile's region is not consulted, so set AWS_REGION when the resources live in another region.

When sts:GetCallerIdentity fails and AWS_ACCOUNT_ID is unset or is not a 12-digit account id, a name that needs the account stays unresolved. If a recorded property needs the account too, cdkd warns and records that resource's properties as the template wrote them, intrinsic functions included.

--record-resource-mapping

This flag writes the ids cdkd resolved to a JSON file. Run it once where the lookups work, then replay the file in CI so that the run needs no lookup and no prompt:

# writes what cdkd resolved
cdkd import MyStack --record-resource-mapping ./mapping.json

# replays it without prompts
cdkd import MyStack --resource-mapping ./mapping.json --yes

cdkd writes the file before the confirmation prompt, so it is also written when you answer no or pass --dry-run.

--migrate-from-cloudformation

Migrating from cdk deploy walks through a migration. The details below matter for a nested, large or YAML-authored stack.

Nested stacks

cdkd writes one state file per nested stack:

cdkd/<parent>~<childLogicalId>/<region>/state.json
cdkd/<parent>~<child>~<grandchild>/<region>/state.json

It sets Retain on every resource at every depth. Deleting the parent CloudFormation stack then removes the child stack records with it.

Before it writes any state, cdkd compares the nested stacks in the template with the ones in AWS. A nested stack that exists on one side only stops the import with an error that names the logical ID.

Template size and format

To set Retain, cdkd submits a modified copy of the stack's template to CloudFormation.

A YAML template is supported. Shorthand intrinsic functions (!Ref, !Sub, !GetAtt) are preserved, and cdkd submits the update as YAML.

Permissions for the uploaded-template cleanup

The state bucket is versioned, so deleting an uploaded template would leave its content readable as an earlier version of the object. cdkd therefore deletes those earlier versions too, which needs s3:ListBucketVersions and s3:DeleteObjectVersion on the state bucket.

Without those two permissions the migration still succeeds, and a warning names them.

The cleanup reaches the state bucket only. If the bucket is replicated, the template's content survives in the destination bucket, and cdkd warns when it can read the replication configuration. State Management has a bucket policy that grants both actions and explains the replication limit.

cdkd import vs upstream cdk import

cdkd accepts the same mapping flags as upstream cdk import, but works differently underneath. cdk import submits one CloudFormation IMPORT changeset, which either applies in full or rolls back. cdkd import calls each service directly, one resource at a time, and writes state for the resources that succeeded.

If your scripts rely on the upstream behaviour:

• A mapping file or inline mapping works unchanged.
• Replace the interactive prompt with --resource-mapping <file>, because cdkd does not prompt for ids.
• There is no automatic rollback. To back out of a partial import, run cdkd state orphan MyStack, which drops the state record only.
• --force has the same name and a different meaning.

Related

• Importing Existing Resources: the walkthroughs
• Importing by resource type: the --resource value for each type
• After an import: the first diff, the drift baseline, and removing a secret from state
• Import internals: how the nested-stack migration works