cdkd export: nested stacks

cdkd export exports a stack together with every nested stack under it. You name the root stack, and cdkd handles the tree:

cdkd export MyApp --dry-run   # per-stack plan for the whole tree
cdkd export MyApp

cdkd exports the tree one stack at a time, starting with the stacks that have no nested stacks of their own. Each cdkd stack in the tree becomes its own CloudFormation stack. Each parent then adopts its children as nested stacks, so the tree has the same shape in CloudFormation afterwards.

The export works this way because CloudFormation offers no single changeset for a tree: it rejects IncludeNestedStacks on an IMPORT changeset.

cdkd asks for one tree-wide confirmation before it exports the first stack.

Child stack names

cdkd names a nested stack <parent>~<childLogicalId>. CloudFormation does not allow ~ in a stack name, so the export names the CloudFormation stack <parent>-<childLogicalId>.

To choose a different name for one child, pass --cfn-child-stack-name with the cdkd name and the CloudFormation name. The flag can be repeated:

cdkd export MyApp --cfn-child-stack-name 'MyApp~Database=my-app-db'

Child Parameters

A parent's template passes Parameters to each nested stack. After the export a child is imported with its own changeset, so cdkd works out each Parameter's value and submits it with that changeset.

What the child receives depends on the value the parent passes. cdkd resolves a Ref or Fn::GetAtt from the parent's Parameters and from cdkd state.

A value cdkd cannot resolve

cdkd prints a warning and passes no value for that Parameter. The child template's Default then has to cover it. Check the --dry-run plan for these warnings before you export.

A value that is masked

cdkd stores *** in state in place of a secret, and *** is not the value the child needs. The export refuses with EXPORT_MASKED_CHILD_PARAMETER. When a recorded value is *** has the remedy.

A parent's SSM-typed Parameter

An SSM-typed Parameter has a type such as AWS::SSM::Parameter::Value<String>. Its value is the name of an SSM parameter, and CloudFormation looks the stored value up. The child needs that stored value, so cdkd reads it with ssm:GetParameter, without decryption.

cdkd export therefore needs the ssm:GetParameter permission on each SSM parameter that a child's Parameters mention.

The export refuses if the read fails, or if the SSM parameter is not a String or StringList. It refuses before it locks any nested stack or submits any changeset. --dry-run prints a warning instead.

When one stack of the tree fails

Each stack that was imported before the failure has a CloudFormation stack. cdkd keeps its state for the failed stack and for every stack that was not imported yet. The error names the stacks that moved and the ones that remain.

Running cdkd export again does not resume. The command refuses a tree while any of its CloudFormation stacks exists, and every stack imported before the failure has one. You finish the migration by hand, following the steps the error prints:

• Run cdkd state orphan <stack> --stack-region <region> for each stack that finished. Run it for the failed stack too, once you have completed the steps the error names for that stack.
• If the failed stack has a phase 2, run the inline-policy deletes the error lists before that phase. cdkd export: custom resources and IAM policies explains phase 2.
• Migrate the stacks that were not imported yet with a CloudFormation IMPORT by hand. Adopt nested children as AWS's "Nest an existing stack" procedure describes.

When the first stack fails

If the import of the first stack fails, nothing was imported, and you can start over:

1. Run the aws cloudformation list-stack-resources command that cdkd prints, and confirm that the CloudFormation stack the failed import left holds no resources.
2. Delete that CloudFormation stack.
3. Run cdkd export again.

Related

• cdkd export: the command, the run order and the options
• cdkd export: what blocks an export: including a nested stack whose state record is missing
• cdkd export: the template CloudFormation receives: Parameters of the root stack
• cdkd export internals: the changeset sequence cdkd submits per stack, for contributors