Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(cli): CDK Migrate CLI command #27325

Merged
merged 27 commits into from
Oct 6, 2023
Merged
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 121 additions & 0 deletions packages/aws-cdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ The AWS CDK Toolkit provides the `cdk` command-line interface that can be used t
| [`cdk diff`](#cdk-diff) | Diff stacks against current state |
| [`cdk deploy`](#cdk-deploy) | Deploy a stack into an AWS account |
| [`cdk import`](#cdk-import) | Import existing AWS resources into a CDK stack |
| [`cdk migrate`](#cdk-migrate) | Convert an existing CFN template into a CDK Application |
| [`cdk watch`](#cdk-watch) | Watches a CDK app for deployable and hotswappable changes |
| [`cdk destroy`](#cdk-destroy) | Deletes a stack from an AWS account |
| [`cdk bootstrap`](#cdk-bootstrap) | Deploy a toolkit stack to support deploying large stacks & artifacts |
Expand Down Expand Up @@ -560,6 +561,126 @@ This feature currently has the following limitations:
bucket). Requires version 12 of the bootstrap stack, for the added
IAM permissions to the `deploy-role`.


### `cdk migrate`

⚠️**CAUTION**⚠️

CDK Migrate is currently experimental and may have breaking changes in the future.

CDK Migrate Generates a CDK application using an existing CloudFormation template in JSON or YAML format.
Templates can be provided from either from a local file using `--from-path` or directly from a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Templates can be provided from either from a local file using `--from-path` or directly from a
Templates can be provided either from a local file using `--from-path` or directly from a

deployed CloudFormation stack with `--from-stack`. The generated CDK application will
synthesize a CloudFormation template with identical resource configurations to the provided template.
The generated application will be initialized in the current working directory with a single stack where
the stack, app, and directory will all be named using the provided `--stack-name`. It will also
be within a generated subdirectory in your current working directory unless `--output-path` is specified.
If a directory already exists with the same name as `--stack-name`, it will be replaced with the new application.
All CDK supported languages are supported, language choice can be specified with `--language`.

#### Generate a typescript application from a local template.json file
comcalvi marked this conversation as resolved.
Show resolved Hide resolved

```console
$ # template.json is a valid cloudformation template in the local directory
$ cdk migrate --stack-name MyAwesomeApplication --language typescript --from-path MyTemplate.json
```

This command will generate a new directory named `MyAwesomeApplication` within your current working directory, and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't match the name used above

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed it in the console command. Surprised this doesn't show up as outdated

then initialize a new CDK application within that directory which has the same resource configuration
as the provided template.json

This results in a CDK application with the following structure, where the lib directory contains a stack definition
with the same resource configuration as the provided template.json.

```console
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also doesn't match the command you provide above. Both the naming and the language are different.

├── README.md
├── bin
│ └── my_awesome_application.ts
├── cdk.json
├── jest.config.js
├── lib
│ └── my_awesome_application-stack.ts
├── package.json
├── tsconfig.json
```

#### Generate a python application from a deployed stack

If you already have a CloudFormation stack deployed in your account and would like to manage it with CDK, you can use the
`--from-stack` option to generate the application. In this case the `--stack-name` must match the name of the deployed stack.

```console
$ # generate a python application from MyDeployedStack in your account
$ cdk migrate --stack-name MyDeployedStack --language python --from-stack
```

This will generate a Python CDK application which will synthesize the same configuration of resources as the deployed stack.

#### **CDK Migrate Limitations**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be good to call out support for Custom Resources.

Copy link
Contributor Author

@HBobertz HBobertz Oct 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this and nested stacks

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, and ADC regions will depend on those resources existing in those regions. The app will still synth but may not deploy


- CDK Migrate does not currently support nested stacks, custom resources, or the `Fn::ForEach` intrinsic function.

- CDK Migrate will only generate L1 constructs and does not currently support any higher level abstractions.

- CDK Migrate successfully generating an application does *not* guarantee the application is immediately deployable.
It simply generates a CDK application which will synthesize a template that has identical resource configurations
to the provided template.

- CDK Migrate does not interact with the CloudFormation service to verify the template
provided can deploy on its own. This means CDK Migrate will not verify that any resources in the provided
template are already managed in other CloudFormation templates, nor will it verify that the resources in the provided
template are available in the desired regions, which may impact ADC or Opt-In regions.

- If the provided template has parameters without default values, those will need to be provided
before deploying the generated application.

In practice this is how CDK Migrate generated applications will operate in the following scenarios:

| Situation | Result |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Provided template + stack-name is from a deployed stack in the account/region | The CDK application will deploy as a changeset to the existing stack |
| Provided template has no overlap with resources already in the account/region | The CDK application will deploy a new stack successfully |
| Provided template has overlap with Cloudformation managed resources already in the account/region | The CDK application will not be deployable unless those resources are removed |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| Provided template has overlap with Cloudformation managed resources already in the account/region | The CDK application will not be deployable unless those resources are removed |
| Provided template has overlap with CloudFormation managed resources already in the account/region | The CDK application will not be deployable unless those resources are removed |

| Provided template has overlap with unmanaged resources already in the account/region | The CDK application will not be deployable until those resources are adopted with [`cdk import`](#cdk-import) |


##### **The provided template is already deployed to CloudFormation in the account/region**

If the provided template came directly from a deployed CloudFormation stack, and that stack has not experienced any drift,
then the generated application will be immediately deployable, and will not cause any changes to the deployed resources.
Drift might occur if a resource in your template was modified outside of CloudFormation, namely via the AWS Console or AWS CLI.

##### **The provided template is not deployed to CloudFormation in the account/region, and there *is not* overlap with existing resources in the account/region**

If the provided template represents a set of resources that have no overlap with resources already deployed in the account/region,
then the generated application will be immediately deployable. This could be because the stack has never been deployed, or
the application was generated from a stack deployed in another account/region.

In practice this means for any resource in the provided template, for example,

```Json
"S3Bucket": {
"Type": "AWS::S3::Bucket",
"Properties": {
"BucketName": "MyBucket",
"AccessControl": "PublicRead",
},
"DeletionPolicy": "Retain"
}
```

There must not exist a resource of that type with the same identifier in the desired region. In this example that identfier
would be "MyBucket"

##### **The provided template is not deployed to CloudFormation in the account/region, and there *is* overlap with existing resources in the account/region**

If the provided template represents a set of resources that overlap with resources already deployed in the account/region,
then the generated application will not be immediately deployable. If those overlapped resources are already managed by
another CloudFormation stack in that account/region, then those resources will need to be manually removed from the provided
template. Otherwise, if the overlapped resources are not managed by another CloudFormation stack, then first remove those
resources from your CDK Application Stack, deploy the cdk application successfully, then re-add them and run `cdk import`
to import them into your deployed stack.

### `cdk destroy`

Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were
Expand Down
Loading