Frequently asked questions

Short answers to the questions people ask before or soon after their first deploy.

On this page:

Q: Is a CloudFormation stack created?
Q: Can I use CloudFormation and cdkd for the same stack?
Q: What happens if I delete the state file?
Q: Is there a rollback feature?
Q: Are custom resources supported?

Q: Is a CloudFormation stack created?

No. cdkd deploy provisions each resource directly, through an SDK provider or the Cloud Control API. There is no CloudFormation stack, change set or stack events. The equivalents are cdkd state show and cdkd events. See Provisioning Layers.

Two cases do touch CloudFormation:

A template declaring a macro (Transform / Fn::Transform, for example SAM) is expanded by CloudFormation. cdkd creates a temporary cdkd-macro-expand-* stack, reads the processed template and deletes the stack before provisioning anything.
cdkd export creates a real CloudFormation stack, because that is how it hands a stack over.

Q: Can I use CloudFormation and cdkd for the same stack?

Not at the same time. One stack has one owner at a time, but you can hand a stack over in either direction, and neither handover changes the AWS resources.

# CloudFormation -> cdkd
cdkd import MyStack --migrate-from-cloudformation

# cdkd -> CloudFormation: print the plan
cdkd export MyStack --dry-run
cdkd export MyStack

To cdkd: the import adopts the resources and retires the CloudFormation stack record. It needs a CDK app that synthesizes the stack. Nested stacks are walked recursively. See Importing Existing Resources.
To CloudFormation: the export builds an IMPORT change set, executes it and deletes cdkd state. It is all-or-nothing. It refuses up front on a resource with no state entry, a masked value in the recorded properties, a type CloudFormation cannot import, or a custom resource without --include-non-importable. See cdkd export.

Different stacks can stay on different engines. A cdkd-deployed stack resolves Fn::ImportValue / Fn::GetStackOutput against a CloudFormation-managed producer with no change on the producer side.

Q: What happens if I delete the state file?

cdkd no longer knows any of the stack's resources, so the next cdkd deploy plans every one as a create. What happens then depends on the type:

Types	Result of the create
Most types	Fails with an already-exists error
`AWS::S3::Bucket`, `AWS::Logs::LogGroup`, `AWS::SNS::Topic`	Adopts the existing resource and re-applies your configuration over it
Types with an AWS-assigned id: VPC, EC2 instance, ACM certificate, CloudFront distribution	Creates a second resource and orphans the first, once per attempt

To recover, leave the AWS resources in place and adopt them back into state:

cdkd import MyStack --dry-run   # preview; writes no state
cdkd import MyStack

cdkd import finds each resource by the name in the template, then through a CloudFormation stack of the same name. A resource whose name cdkd generated has no name in the template and is reported not found. Name those explicitly, copying the name AWS reports:

cdkd import MyStack --resource MyBucket=mystack-mybucket

A generated name is <StackName>-<LogicalId> when that fits the type's length limit. Otherwise it is truncated with - and 8 hex characters appended (mystack-averylongconstructna-19184149). See Importing Existing Resources.

Q: Is there a rollback feature?

Yes. cdkd rolls back on failure by default. --no-rollback keeps the partial state instead, and the next deploy applies the remaining changes. To return a --no-rollback or interrupted deploy to its pre-deploy state, run cdkd rollback MyStack. See Rollback.

Q: Are custom resources supported?

Yes. Both type spellings work (Custom::<Name> and AWS::CloudFormation::CustomResource), and both ServiceToken forms:

Lambda-backed: cdkd invokes the function. The handler returns the response directly or PUTs it to the pre-signed ResponseURL.
SNS-backed: cdkd publishes the request to the topic and polls for the response.

CDK's Provider framework (onEventHandler + isCompleteHandler) is detected automatically and gets a longer timeout, one hour by default. Change it with:

cdkd deploy MyStack --resource-timeout AWS::CloudFormation::CustomResource=2h

cdkd export cannot hand a custom resource to CloudFormation without --include-non-importable.

Troubleshooting: the common problems and the list of every troubleshooting page