You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(migrate): update readme to reflect migrate from scan feature (aws#28961)
How the readme looks below
| [`cdk migrate`](#cdk-migrate) | Migrate AWS resources, CloudFormation stacks, and CloudFormation templates to CDK |
### `cdk migrate`
⚠️**CAUTION**⚠️: CDK Migrate is currently experimental and may have breaking changes in the future.
CDK Migrate generates a CDK app from deployed AWS resources using `--from-scan`, deployed AWS CloudFormation stacks using `--from-stack`, and local AWS CloudFormation templates using `--from-path`.
To learn more about the CDK Migrate feature, see [Migrate to AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html). For more information on `cdk migrate` command options, see [cdk migrate command reference](https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cdk-migrate.html).
The new CDK app will be initialized in the current working directory and will include a single stack that is named with the value you provide using `--stack-name`. The new stack, app, and directory will all use this name. To specify a different output directory, use `--output-path`. You can create the new CDK app in any CDK supported programming language using `--language`.
#### Migrate from an AWS CloudFormation stack
Migrate from a deployed AWS CloudFormation stack in a specific AWS account and AWS Region using `--from-stack`. Provide `--stack-name` to identify the name of your stack. Account and Region information are retrieved from default CDK CLI sources. Use `--account` and `--region` options to provide other values. The following is an example that migrates **myCloudFormationStack** to a new CDK app using TypeScript:
```console
$ cdk migrate --language typescript --from-stack --stack-name 'myCloudFormationStack'
```
#### Migrate from a local AWS CloudFormation template
Migrate from a local `YAML` or `JSON` AWS CloudFormation template using `--from-path`. Provide a name for the stack that will be created in your new CDK app using `--stack-name`. Account and Region information are retrieved from default CDK CLI sources. Use `--account` and `--region` options to provide other values. The following is an example that creates a new CDK app using TypeScript that includes a **myCloudFormationStack** stack from a local `template.json` file:
```console
$ cdk migrate --language typescript --from-path "./template.json" --stack-name "myCloudFormationStack"
```
#### Migrate from deployed AWS resources
Migrate from deployed AWS resources in a specific AWS account and Region that are not associated with an AWS CloudFormation stack using `--from-scan`. These would be resources that were provisioned outside of an IaC tool. CDK Migrate utilizes the IaC generator service to scan for resources and generate a template. Then, the CDK CLI references the template to create a new CDK app. To learn more about IaC generator, see [Generating templates for existing resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html).
Account and Region information are retrieved from default CDK CLI sources. Use `--account` and `--region` options to provide other values. The following is an example that creates a new CDK app using TypeScript that includes a new **myCloudFormationStack** stack from deployed resources:
```console
$ cdk migrate --language typescript --from-scan --stack-name "myCloudFormationStack"
```
Since CDK Migrate relies on the IaC generator service, any limitations of IaC generator will apply to CDK Migrate. For general limitations, see [Considerations](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html#generate-template-considerations).
IaC generator limitations with discovering resource and property values will also apply here. As a result, CDK Migrate will only migrate resources supported by IaC generator. Some of your resources may not be supported and some property values may not be accessible. For more information, see [Iac generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html) and [Supported resource types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-supported-resources.html).
You can specify filters using `--filter` to specify which resources to migrate. This is a good option to use if you are over the IaC generator total resource limit.
After migration, you must resolve any write-only properties that were detected by IaC generator from your deployed resources. To learn more, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly).
#### Examples
##### Generate a TypeScript CDK app from a local AWS CloudFormation template.json file
```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 generates a new directory named `MyAwesomeApplication` within your current working directory, and
then initializes a new CDK application within that directory. The CDK app contains a `MyAwesomeApplication` stack with resources configured to match those in your local CloudFormation template.
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
├── 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 CDK app 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 migrate the deployed stack to a new CDK app. The value provided with `--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 app which will synthesize the same configuration of resources as the deployed stack.
##### Generate a TypeScript CDK app from deployed AWS resources that are not associated with a stack
If you have resources in your account that were provisioned outside AWS IaC tools and would like to manage them with the CDK, you can use the `--from-scan` option to generate the application.
In this example, we use the `--filter` option to specify which resources to migrate. You can filter resources to limit the number of resources migrated to only those specified by the `--filter` option, including any resources they depend on, or resources that depend on them (for example A filter which specifies a single Lambda Function, will find that specific table and any alarms that may monitor it). The `--filter` argument offers both AND as well as OR filtering.
OR filtering can be specified by passing multiple `--filter` options, and AND filtering can be specified by passing a single `--filter` option with multiple comma separated key/value pairs as seen below (see below for examples). It is recommended to use the `--filter` option to limit the number of resources returned as some resource types provide sample resources by default in all accounts which can add to the resource limits.
`--from-scan` takes 3 potential arguments: `--new`, `most-recent`, and undefined. If `--new` is passed, CDK Migrate will initiate a new scan of the account and use that new scan to discover resources. If `--most-recent` is passed, CDK Migrate will use the most recent scan of the account to discover resources. If neither `--new` nor `--most-recent` are passed, CDK Migrate will take the most recent scan of the account to discover resources, unless there is no recent scan, in which case it will initiate a new scan.
```
# Filtering options
identifier|id|resource-identifier=<resource-specific-resource-identifier-value>
type|resource-type-prefix=<resource-type-prefix>
tag-key=<tag-key>
tag-value=<tag-value>
```
##### Additional examples of migrating from deployed resources
```console
$ # Generate a typescript application from all un-managed resources in your account
$ cdk migrate --stack-name MyAwesomeApplication --language typescript --from-scan
$ # Generate a typescript application from all un-managed resources in your account with the tag key "Environment" AND the tag value "Production"
$ cdk migrate --stack-name MyAwesomeApplication --language typescript --from-scan --filter tag-key=Environment,tag-value=Production
$ # Generate a python application from any dynamoDB resources with the tag-key "dev" AND the tag-value "true" OR any SQS::Queue
$ cdk migrate --stack-name MyAwesomeApplication --language python --from-scan --filter type=AWS::DynamoDb::,tag-key=dev,tag-value=true --filter type=SQS::Queue
$ # Generate a typescript application from a specific lambda function by providing it's specific resource identifier
$ cdk migrate --stack-name MyAwesomeApplication --language typescript --from-scan --filter identifier=myAwesomeLambdaFunction
```
#### **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 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 un-managed resources already in the account/region | The CDK application will not be deployable until those resources are adopted with [`cdk import`](#cdk-import) |
| No template has been provided and resources exist in the region the scan is done | The CDK application will be immediatly deployable and will import those resources into a new cloudformation stack upon deploy |
##### **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.
----
*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
|[`cdk docs`](#cdk-docs)| Access the online documentation |
17
+
|[`cdk init`](#cdk-init)| Start a new CDK project (app or library) |
18
+
|[`cdk list`](#cdk-list)| List stacks in an application |
19
+
|[`cdk synth`](#cdk-synthesize)| Synthesize a CDK app to CloudFormation template(s) |
20
+
|[`cdk diff`](#cdk-diff)| Diff stacks against current state |
21
+
|[`cdk deploy`](#cdk-deploy)| Deploy a stack into an AWS account |
22
+
|[`cdk import`](#cdk-import)| Import existing AWS resources into a CDK stack |
23
+
|[`cdk migrate`](#cdk-migrate)|Migrate AWS resources, CloudFormation stacks, and CloudFormation templates to CDK|
24
+
|[`cdk watch`](#cdk-watch)| Watches a CDK app for deployable and hotswappable changes |
25
+
|[`cdk destroy`](#cdk-destroy)| Deletes a stack from an AWS account |
26
+
|[`cdk bootstrap`](#cdk-bootstrap)| Deploy a toolkit stack to support deploying large stacks & artifacts |
27
+
|[`cdk doctor`](#cdk-doctor)| Inspect the environment and produce information useful for troubleshooting |
28
+
|[`cdk acknowledge`](#cdk-acknowledge)| Acknowledge (and hide) a notice by issue number |
29
+
|[`cdk notices`](#cdk-notices)| List all relevant notices for the application |
30
30
31
31
-[Bundling](#bundling)
32
32
-[MFA Support](#mfa-support)
@@ -594,30 +594,59 @@ This feature currently has the following limitations:
594
594
595
595
### `cdk migrate`
596
596
597
-
⚠️**CAUTION**⚠️
597
+
⚠️**CAUTION**⚠️: CDK Migrate is currently experimental and may have breaking changes in the future.
598
598
599
-
CDK Migrate is currently experimental and may have breaking changes in the future.
599
+
CDK Migrate generates a CDK app from deployed AWS resources using `--from-scan`, deployed AWS CloudFormation stacks using `--from-stack`, and local AWS CloudFormation templates using `--from-path`.
600
600
601
-
CDK Migrate Generates a CDK application using an existing CloudFormation template in JSON or YAML format.
602
-
Templates can be provided from either from a local file using `--from-path` or directly from a
603
-
deployed CloudFormation stack with `--from-stack`. The generated CDK application will
604
-
synthesize a CloudFormation template with identical resource configurations to the provided template.
605
-
The generated application will be initialized in the current working directory with a single stack where
606
-
the stack, app, and directory will all be named using the provided `--stack-name`. It will also
607
-
be within a generated subdirectory in your current working directory unless `--output-path` is specified.
608
-
If a directory already exists with the same name as `--stack-name`, it will be replaced with the new application.
609
-
All CDK supported languages are supported, language choice can be specified with `--language`.
601
+
To learn more about the CDK Migrate feature, see [Migrate to AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html). For more information on `cdk migrate` command options, see [cdk migrate command reference](https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cdk-migrate.html).
610
602
611
-
#### Generate a typescript application from a local template.json file
603
+
The new CDK app will be initialized in the current working directory and will include a single stack that is named with the value you provide using `--stack-name`. The new stack, app, and directory will all use this name. To specify a different output directory, use `--output-path`. You can create the new CDK app in any CDK supported programming language using `--language`.
604
+
605
+
#### Migrate from an AWS CloudFormation stack
606
+
607
+
Migrate from a deployed AWS CloudFormation stack in a specific AWS account and AWS Region using `--from-stack`. Provide `--stack-name` to identify the name of your stack. Account and Region information are retrieved from default CDK CLI sources. Use `--account` and `--region` options to provide other values. The following is an example that migrates **myCloudFormationStack** to a new CDK app using TypeScript:
#### Migrate from a local AWS CloudFormation template
614
+
615
+
Migrate from a local `YAML` or `JSON` AWS CloudFormation template using `--from-path`. Provide a name for the stack that will be created in your new CDK app using `--stack-name`. Account and Region information are retrieved from default CDK CLI sources. Use `--account` and `--region` options to provide other values. The following is an example that creates a new CDK app using TypeScript that includes a **myCloudFormationStack** stack from a local `template.json` file:
Migrate from deployed AWS resources in a specific AWS account and Region that are not associated with an AWS CloudFormation stack using `--from-scan`. These would be resources that were provisioned outside of an IaC tool. CDK Migrate utilizes the IaC generator service to scan for resources and generate a template. Then, the CDK CLI references the template to create a new CDK app. To learn more about IaC generator, see [Generating templates for existing resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html).
624
+
625
+
Account and Region information are retrieved from default CDK CLI sources. Use `--account` and `--region` options to provide other values. The following is an example that creates a new CDK app using TypeScript that includes a new **myCloudFormationStack** stack from deployed resources:
Since CDK Migrate relies on the IaC generator service, any limitations of IaC generator will apply to CDK Migrate. For general limitations, see [Considerations](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html#generate-template-considerations).
632
+
633
+
IaC generator limitations with discovering resource and property values will also apply here. As a result, CDK Migrate will only migrate resources supported by IaC generator. Some of your resources may not be supported and some property values may not be accessible. For more information, see [Iac generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html) and [Supported resource types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-supported-resources.html).
634
+
635
+
You can specify filters using `--filter` to specify which resources to migrate. This is a good option to use if you are over the IaC generator total resource limit.
636
+
637
+
After migration, you must resolve any write-only properties that were detected by IaC generator from your deployed resources. To learn more, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly).
638
+
639
+
#### Examples
640
+
641
+
##### Generate a TypeScript CDK app from a local AWS CloudFormation template.json file
612
642
613
643
```console
614
644
$ # template.json is a valid cloudformation template in the local directory
This command will generate a new directory named `MyAwesomeApplication` within your current working directory, and
619
-
then initialize a new CDK application within that directory which has the same resource configuration
620
-
as the provided template.json
648
+
This command generates a new directory named `MyAwesomeApplication` within your current working directory, and
649
+
then initializes a new CDK application within that directory. The CDK app contains a `MyAwesomeApplication` stack with resources configured to match those in your local CloudFormation template.
621
650
622
651
This results in a CDK application with the following structure, where the lib directory contains a stack definition
623
652
with the same resource configuration as the provided template.json.
@@ -634,17 +663,50 @@ with the same resource configuration as the provided template.json.
634
663
├── tsconfig.json
635
664
```
636
665
637
-
#### Generate a python application from a deployed stack
666
+
#####Generate a Python CDK app from a deployed stack
638
667
639
-
If you already have a CloudFormation stack deployed in your account and would like to manage it with CDK, you can use the
640
-
`--from-stack` option to generate the application. In this case the `--stack-name` must match the name of the deployed stack.
668
+
If you already have a CloudFormation stack deployed in your account and would like to manage it with CDK, you can migrate the deployed stack to a new CDK app. The value provided with `--stack-name` must match the name of the deployed stack.
641
669
642
670
```console
643
-
$ # generate a python application from MyDeployedStack in your account
671
+
$ # generate a Python application from MyDeployedStack in your account
This will generate a Python CDK application which will synthesize the same configuration of resources as the deployed stack.
675
+
This will generate a Python CDK app which will synthesize the same configuration of resources as the deployed stack.
676
+
677
+
##### Generate a TypeScript CDK app from deployed AWS resources that are not associated with a stack
678
+
679
+
If you have resources in your account that were provisioned outside AWS IaC tools and would like to manage them with the CDK, you can use the `--from-scan` option to generate the application.
680
+
681
+
In this example, we use the `--filter` option to specify which resources to migrate. You can filter resources to limit the number of resources migrated to only those specified by the `--filter` option, including any resources they depend on, or resources that depend on them (for example A filter which specifies a single Lambda Function, will find that specific table and any alarms that may monitor it). The `--filter` argument offers both AND as well as OR filtering.
682
+
683
+
OR filtering can be specified by passing multiple `--filter` options, and AND filtering can be specified by passing a single `--filter` option with multiple comma separated key/value pairs as seen below (see below for examples). It is recommended to use the `--filter` option to limit the number of resources returned as some resource types provide sample resources by default in all accounts which can add to the resource limits.
684
+
685
+
`--from-scan` takes 3 potential arguments: `--new`, `most-recent`, and undefined. If `--new` is passed, CDK Migrate will initiate a new scan of the account and use that new scan to discover resources. If `--most-recent` is passed, CDK Migrate will use the most recent scan of the account to discover resources. If neither `--new` nor `--most-recent` are passed, CDK Migrate will take the most recent scan of the account to discover resources, unless there is no recent scan, in which case it will initiate a new scan.
@@ -657,7 +719,8 @@ It simply generates a CDK application which will synthesize a template that has
657
719
to the provided template.
658
720
659
721
- CDK Migrate does not interact with the CloudFormation service to verify the template
660
-
provided can deploy on its own. This means CDK Migrate will not verify that any resources in the provided
722
+
provided can deploy on its own. Although by default any CDK app generated using the `--from-scan` option exclude
723
+
CloudFormation managed resources, CDK Migrate will not verify prior to deployment that any resources scanned, or in the provided
661
724
template are already managed in other CloudFormation templates, nor will it verify that the resources in the provided
662
725
template are available in the desired regions, which may impact ADC or Opt-In regions.
663
726
@@ -671,8 +734,8 @@ In practice this is how CDK Migrate generated applications will operate in the f
671
734
| 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 |
672
735
| Provided template has no overlap with resources already in the account/region | The CDK application will deploy a new stack successfully |
673
736
| 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 |
674
-
| 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)|
675
-
737
+
| Provided template has overlap with un-managed resources already in the account/region | The CDK application will not be deployable until those resources are adopted with [`cdk import`](#cdk-import)|
738
+
| No template has been provided and resources exist in the region the scan is done | The CDK application will be immediatly deployable and will import those resources into a new cloudformation stack upon deploy |
676
739
677
740
##### **The provided template is already deployed to CloudFormation in the account/region**
0 commit comments