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

feat(cli): CDK Migrate CLI command #27325

merged 27 commits into from Oct 6, 2023

Conversation

HBobertz
Copy link
Contributor

@HBobertz HBobertz commented Sep 27, 2023

Added CDK migrate command. Here is what it looks like in md

cdk migrate

⚠️CAUTION⚠️

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

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
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

$ # 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
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.

├── 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 had a CloudFormation stack deployed in your account and would like to migrate to using CDK instead of CloudFormation.
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.

$ # generate a python application from MyDeployedStack in your account
$ cdk bootstrap 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

  • 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 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
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
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,

    "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 identifer
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 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 run remove those
resources and deploy the template successfully, then re-add them and run cdk import to import them into your deployed stack.


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@github-actions github-actions bot added the p2 label Sep 27, 2023
@aws-cdk-automation aws-cdk-automation requested a review from a team September 27, 2023 19:46
@mergify mergify bot added the contribution/core This is a PR that came from AWS. label Sep 27, 2023
Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

@HBobertz HBobertz changed the title Docs(core): add CDK Migrate Readme docs(core): add CDK Migrate Readme Sep 27, 2023
@aws-cdk-automation aws-cdk-automation dismissed their stale review September 27, 2023 19:57

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

@@ -746,6 +746,32 @@ NOTICES
If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 16603".
```

### `cdk migrate`

⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.
Copy link
Contributor

Choose a reason for hiding this comment

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

Experimental means that it might have breaking changes in the future. Saying we make no guarantees about the commands output sounds like the command may or may not do what the documentation says, and that is not the case.

Reusing the exact phrasing from another experimental command:

Suggested change
⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.
⚠️**CAUTION**⚠️ This command is considered experimental, and might have breaking changes in the future.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is what we currently output when a user runs our command. Should we change it in both places?

Copy link
Contributor

Choose a reason for hiding this comment

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

I would be in favor of that, yes


Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
Required Arguments:
* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
Copy link
Contributor

Choose a reason for hiding this comment

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

Absolute paths should also work.

Suggested change
* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
* `--from-path <my_file_path>` - The file path to the JSON or YAML CloudFormation template


⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.

Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
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
Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
Generates a CDK application from an existing CloudFormation template in any of the CDK supported languages.

* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
* `--stack-name <my_stack_name>` - Used to name both the CDK application and stack.
Optional Arguments:
* `--output-path <my_output_path>` - file path to where the file should be generated.
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
* `--output-path <my_output_path>` - file path to where the file should be generated.
* `--output-path <my_output_path>` - file path where the application will be generated

Required Arguments:
* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
* `--stack-name <my_stack_name>` - Used to name both the CDK application and stack.
Optional Arguments:
Copy link
Contributor

Choose a reason for hiding this comment

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

This is supposed to be a title - but will show inline and this will all be one paragraph.

⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.

Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
Required Arguments:
Copy link
Contributor

Choose a reason for hiding this comment

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

In md, this will be inlined with the following lines, and not look like a title.

@@ -746,6 +746,32 @@ NOTICES
If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 16603".
```

### `cdk migrate`
Copy link
Contributor

Choose a reason for hiding this comment

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

This section is under the "Notices" section. Can you move it up to the "Commands" section?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

isn't CDK notices the command?

Copy link
Contributor

Choose a reason for hiding this comment

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

no. there is a section header for Notices with cdk notices and cdk acknowledge both under it. If you view this file as rendered markdown, it is clear that this command is not in the right section.

$ cdk bootstrap migrate --from-path ./template.json --stack-name MyAwesome
```

In order for the generated stack to be immediatly deployable, that stack must either already exist in that region/account
Copy link
Contributor

Choose a reason for hiding this comment

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

put a header above this that says "Limitations" like other commands have done (import)

Copy link
Contributor

Choose a reason for hiding this comment

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

Overall this section is pretty confusing, but I am struggling to come up with better phrasing here. I imagine customers will read this and ask, what does it mean to be immediately deployable? How do I know if there is any overlap between existing resources and resources defined in the input template?

An idea to improve clarity would be to separate this into describing the two use cases that work: 1. deploying to an environment with a deployed stack that matches the input template. 2. deploy to an environment with no deployed resources that overlap with your template definition.
Then finally, include the limitations section saying if you try to deploy a stack generated by CDK migrate to an environment that meets any of the following criteria, deployment will fail.

  • resources with the same physical ids already exist
  • a partially-matching stack already exists.

⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.

Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
Required Arguments:
Copy link
Contributor

Choose a reason for hiding this comment

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

Can you add a paragraph above this that explains in more detail what the command is and how to use it? Think about how you would teach someone who is new to CDK how to use this command to get started with CDK.

@@ -746,6 +746,32 @@ NOTICES
If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 16603".
```

### `cdk migrate`

⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.
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
⚠️**CAUTION**⚠️ CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.
⚠️ **CAUTION** ⚠️
CDK migrate is currently experimental. We make no guarantees about the outcome or stability of the Command or it's output.


Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
Required Arguments:
* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
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
* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
* `--from-path <my_file_path>` - Takes the relative file path to the JSON or YAML CloudFormation template

Generates a CDK application from an existing Cloudformation template in any of the CDK supported languages.
Required Arguments:
* `--from-path <my_file_path>` - Takes the relative filse path to the JSON or YAML template of your choice
* `--stack-name <my_stack_name>` - Used to name both the CDK application and stack.
Copy link
Contributor

Choose a reason for hiding this comment

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

How is it used? Is it used verbatim? Is there a transformation that's applied? Is the CDK App name === the stack name?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

At this point the CDK App name === the stack name. We want to change this later. I'll make this more explicit

Comment on lines 758 to 759
* `--output-path <my_output_path>` - file path to where the file should be generated.
Default is the current working directory
Copy link
Contributor

Choose a reason for hiding this comment

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

file? What type of file? Initially I thought this was supposed to be the generated CDK app, which is a folder (or maybe a zip file), but now I'm thinking it means the stack.ts file. If so it should say something like:

* `--output-path <my_output_path>` - path where the generated CDK Stack will be located.
  Default is `./foo.ts`

Copy link
Contributor Author

Choose a reason for hiding this comment

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

unclear by me. Fixing

* `--output-path <my_output_path>` - file path to where the file should be generated.
Default is the current working directory
* `--language <language>` - Which CDK supported language should be generated [typescript, python, csharp, java, go]
default is typesript
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
default is typesript
default is typescript

$ cdk bootstrap migrate --from-path ./template.json --stack-name MyAwesome
```

In order for the generated stack to be immediatly deployable, that stack must either already exist in that region/account
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
In order for the generated stack to be immediatly deployable, that stack must either already exist in that region/account
In order for the generated application to be immediately deployable, that stack must either already exist in that region/account

$ cdk bootstrap migrate --from-path ./template.json --stack-name MyAwesome
```

In order for the generated stack to be immediatly deployable, that stack must either already exist in that region/account
Copy link
Contributor

Choose a reason for hiding this comment

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

Overall this section is pretty confusing, but I am struggling to come up with better phrasing here. I imagine customers will read this and ask, what does it mean to be immediately deployable? How do I know if there is any overlap between existing resources and resources defined in the input template?

An idea to improve clarity would be to separate this into describing the two use cases that work: 1. deploying to an environment with a deployed stack that matches the input template. 2. deploy to an environment with no deployed resources that overlap with your template definition.
Then finally, include the limitations section saying if you try to deploy a stack generated by CDK migrate to an environment that meets any of the following criteria, deployment will fail.

  • resources with the same physical ids already exist
  • a partially-matching stack already exists.

@madeline-k madeline-k changed the title docs(core): add CDK Migrate Readme docs(cli): add CDK Migrate Readme Sep 27, 2023
⚠️**CAUTION**⚠️

CDK migrate is currently experimental and may have breaking changes in the future.
We make no guarantees about the outcome or stability of the Command nor it's output.
Copy link
Contributor

Choose a reason for hiding this comment

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

So we decided to keep this sentence? If we are, a couple typos:

Suggested change
We make no guarantees about the outcome or stability of the Command nor it's output.
We make no guarantees about the outcome or stability of the command nor its output.

Copy link
Contributor

@comcalvi comcalvi Sep 29, 2023

Choose a reason for hiding this comment

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

I don't think we should keep

We make no guarantees about the outcome or stability of the Command nor it's output.

Copy link
Contributor

@comcalvi comcalvi left a comment

Choose a reason for hiding this comment

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

Take a look at the docs for cdk deploy: https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk#cdk-deploy, this read in a similar way.

⚠️**CAUTION**⚠️

CDK migrate is currently experimental and may have breaking changes in the future.
We make no guarantees about the outcome or stability of the Command nor it's output.
Copy link
Contributor

@comcalvi comcalvi Sep 29, 2023

Choose a reason for hiding this comment

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

I don't think we should keep

We make no guarantees about the outcome or stability of the Command nor it's output.

Comment on lines 566 to 568
⚠️**CAUTION**⚠️

CDK migrate is currently experimental and may have breaking changes in the future.
Copy link
Contributor

Choose a reason for hiding this comment

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

It's fine to open with this, but immediately below should be a paragraph explaining what this command does at a high level, including an example of simplest, minimal usage, eg only using required flags / options. It should explain where the output goes and what the output is. I should not have to guess if it's a full CDK directory or if it's a single stack file.

CDK migrate is currently experimental and may have breaking changes in the future.
We make no guarantees about the outcome or stability of the Command nor it's output.

Generates a CDK application from an existing CloudFormation template in any of the CDK supported languages.
Copy link
Contributor

Choose a reason for hiding this comment

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

This is the first sentence of that opening paragraph. Comparing this to cdk deploy's entry in this file, notice how cdk deploy has a similar opening sentence, but then goes into a high level overview of the command before it gets into use cases.

Notice also how cdk deploy is organized into use cases, not flag entries. Notice also how the use cases are written in the format of:

  • problem statement
  • solution
  • example
  • details

A good example of this format is the deployment progress entry. It starts with:

By default, stack deployment events are displayed as a progress bar with the events for the resource currently being deployed.

This tells user that all the stack deployment history is obscured by default. This is a problem because users may want the full stack history (we could improve this slightly by explicitly stating that the deployment history is obscured). The doc then shows a solution:

Set the --progress flag to request the complete history which includes all CloudFormation events

and immediately follows with an example that shows how to use that solution:

$ cdk deploy --progress events

It then goes into details about flag usage.

Comment on lines 574 to 580
#### Required Arguments:

(You must specify either `--from-path` or `--from-stack`)

* `--stack-name <my_stack_name>` - The name for both the CDK application and stack.
* `--from-path <my_file_path>` - Takes the relative file path to the JSON or YAML CloudFormation template
* `--from-stack` - Retrieves a deployed cloudformation stack from your account with the same name as `--stack-name`.
Copy link
Contributor

Choose a reason for hiding this comment

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

Do not organize the flag usage like this.

By starting with the flags, you're starting from the solutions. But users are reading this doc with a problem in their head. If you think of the readme as a hash table, the keys are problems and the values are solutions. Users reading this doc want to be able to do (in their head):

const solutionToMyProblem = README[myUseCase]

When you organize this with flags (solutions) at the top level, that mental operation doesn't work, because the doc's keys are the solutions, and not the problems.

Yes, flags can be named in such a way that they are obviously what you want (eg, --disable-rollback), but this will never work for all flags. You have more expressiveness with a markdown heading than you do a CLI flag name, so well-named markdown headings will always be easier to parse than CLI flags.

@evgenyka
Copy link
Contributor

evgenyka commented Oct 3, 2023

Shall we call out that generated CDK app will have L1 constructs?


This will generate a python CDK application which will synthesize to 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

@HBobertz HBobertz marked this pull request as ready for review October 3, 2023 19:54
Copy link
Contributor

@comcalvi comcalvi left a comment

Choose a reason for hiding this comment

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

This is in a much better state than it was, nice work! I only have minor comments.

packages/aws-cdk/README.md Show resolved Hide resolved
packages/aws-cdk/README.md Outdated Show resolved Hide resolved
packages/aws-cdk/README.md Outdated Show resolved Hide resolved
Comment on lines 643 to 644
then the generated application will be immediately deployable. A common reason for this might be because the template came
from a stack deployed in another account/region.
Copy link
Contributor

Choose a reason for hiding this comment

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

A common reason for this might be

A common reason for what?

}
```

There must not exist a resource of that type with the same name aka "MyBucket"
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
There must not exist a resource of that type with the same name aka "MyBucket"
There must not exist a resource of that type with the same name, e.g. "MyBucket"

Copy link
Contributor

@madeline-k madeline-k left a comment

Choose a reason for hiding this comment

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

This is looking really great! I just have some comments on grammar/spelling and one content question.

packages/aws-cdk/README.md Outdated Show resolved Hide resolved
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`. The generated application will
be within a generated subdirectory in your current working directory unless `--output-path` is specified.
All CDK supported lanaguages are supported, language choice can be specified with `--language`.
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
All CDK supported lanaguages are supported, language choice can be specified with `--language`.
All CDK supported languages are supported, language choice can be specified with `--language`.

$ cdk migrate --from-path ./template.json --stack-name MyAwesomeApplication
```

This command will generate a new direcotry 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.

Suggested change
This command will generate a new direcotry named `MyAwesomeApplication` within your current working directory, and
This command will generate a new directory named `MyAwesomeApplication` within your current working directory, and

Comment on lines 588 to 589
then initialize a new CDK application within that directory which has the same resource configuration as the
as the provided template.json
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
then initialize a new CDK application within that directory which has the same resource configuration as the
as the provided template.json
then initialize a new CDK application within that directory which has the same resource configuration
as the provided template.json

├── bin
│ └── my_awesome_application.ts
├── cdk.json
├── cdk.out
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we remove cdk.out since it won't exist until after synth?


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 console or CLI.
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
Drift might occur if a resource in your template was modified outside of CloudFormation, namely via the console or CLI.
Drift might occur if a resource in your template was modified outside of CloudFormation, namely via the AWS Console or AWS CLI.

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

##### **The provided template is already deployed to cloudformation in the account/region**
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
##### **The provided template is already deployed to cloudformation in the account/region**
##### **The provided template is already deployed to CloudFormation in the account/region**

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 console or CLI.

##### **The provided template is not deployed to cloudformation in the account/region, and there *is not* overlap with with resources outside the template**
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
##### **The provided template is not deployed to cloudformation in the account/region, and there *is not* overlap with with resources outside the template**
##### **The provided template is not deployed to CloudFormation in the account/region, and there *is not* overlap with existing resources in the account/region**

then the generated application will be immediately deployable. A common reason for this might be because the template came
from a stack deployed in another account/region.

In practice this means for any resource in the provided template. i.e.
Copy link
Contributor

Choose a reason for hiding this comment

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

"i.e." means "that is", and "e.g." means "for example". I think it's better not to use those anyway.

Suggested change
In practice this means for any resource in the provided template. i.e.
In practice this means for any resource in the provided template, for example,


There must not exist a resource of that type with the same name aka "MyBucket"

##### **The provided template is not deployed to cloudformation in the account/region, and there *is* overlap with with resources outside the template**
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
##### **The provided template is not deployed to cloudformation in the account/region, and there *is* overlap with with resources outside the template**
##### **The provided template is not deployed to CloudFormation in the account/region, and there *is* overlap with existing resources in the account/region**

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

Copy link
Collaborator

@aws-cdk-automation aws-cdk-automation left a comment

Choose a reason for hiding this comment

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

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.