diff --git a/packages/aws-cdk/README.md b/packages/aws-cdk/README.md index f50fb6509b1f9..265f4a39f1b7c 100644 --- a/packages/aws-cdk/README.md +++ b/packages/aws-cdk/README.md @@ -19,6 +19,7 @@ Command | Description [`cdk synth`](#cdk-synthesize) | Synthesize a CDK app to CloudFormation template(s) [`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 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 @@ -450,6 +451,53 @@ $ cdk watch --no-logs **Note**: This command is considered experimental, and might have breaking changes in the future. +### `cdk import` + +Sometimes you want to import AWS resources that were created using other means +into a CDK stack. For some resources (like Roles, Lambda Functions, Event Rules, +...), it's feasible to create new versions in CDK and then delete the old +versions. For other resources, this is not possible: stateful resources like S3 +Buckets, DynamoDB tables, etc., cannot be easily deleted without impact on the +service. + +`cdk import`, which uses [CloudFormation resource +imports](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html), +makes it possible to bring an existing resource under CDK/CloudFormation's +management. See the [list of resources that can be imported here](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html). + +To import an existing resource to a CDK stack, follow the following steps: + +1. Run a `cdk diff` to make sure there are no pending changes to the CDK stack you want to + import resources into. The only changes allowed in an "import" operation are + the addition of new resources which you want to import. +2. Add constructs for the resources you want to import to your Stack (for example, + for an S3 bucket, add something like `new s3.Bucket(this, 'ImportedS3Bucket', {});`). + **Do not add any other changes!** You must also make sure to exactly model the state + that the resource currently has. For the example of the Bucket, be sure to + include KMS keys, life cycle policies, and anything else that's relevant + about the bucket. If you do not, subsequent update operations may not do what + you expect. +3. Run the `cdk import` - if there are multiple stacks in the CDK app, pass a specific + stack name as an argument. +4. The CLI will prompt you to pass in the actual names of the resources you are + importing. After you supply it, the import starts. +5. When `cdk import` reports success, the resource is managed by CDK. Any subsequent + changes in the construct configuration will be reflected on the resource. + +#### Limitations + +This feature is currently in preview. Be aware of the following limitations: + +- Importing resources in nested stacks is not possible. +- Uses the deploy role credentials (necessary to read the encrypted staging + bucket). Requires a new version (version 12) of the bootstrap stack, for the added + IAM permissions to the `deploy-role`. +- There is no check on whether the properties you specify are correct and complete + for the imported resource. Try starting a drift detection operation after importing. +- Resources that depend on other resources must all be imported together, or one-by-one + in the right order. The CLI will not help you import dependent resources in the right + order, the CloudFormation deployment will fail with unresolved references. + ### `cdk destroy` Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were @@ -521,10 +569,10 @@ NOTICES 16603 Toggling off auto_delete_objects for Bucket empties the bucket Overview: If a stack is deployed with an S3 bucket with - auto_delete_objects=True, and then re-deployed with - auto_delete_objects=False, all the objects in the bucket + auto_delete_objects=True, and then re-deployed with + auto_delete_objects=False, all the objects in the bucket will be deleted. - + Affected versions: <1.126.0. More information at: https://github.com/aws/aws-cdk/issues/16603 @@ -533,12 +581,12 @@ NOTICES 17061 Error when building EKS cluster with monocdk import Overview: When using monocdk/aws-eks to build a stack containing - an EKS cluster, error is thrown about missing + an EKS cluster, error is thrown about missing lambda-layer-node-proxy-agent/layer/package.json. - + Affected versions: >=1.126.0 <=1.130.0. - More information at: https://github.com/aws/aws-cdk/issues/17061 + More information at: https://github.com/aws/aws-cdk/issues/17061 If you don’t want to see an notice anymore, use "cdk acknowledge ID". For example, "cdk acknowledge 16603". @@ -580,7 +628,7 @@ $cdk acknowledge 16603 ### `cdk notices` List the notices that are relevant to the current CDK repository, regardless of context flags or notices that -have been acknowledged: +have been acknowledged: ```console $ cdk notices @@ -589,9 +637,9 @@ NOTICES 16603 Toggling off auto_delete_objects for Bucket empties the bucket - Overview: if a stack is deployed with an S3 bucket with - auto_delete_objects=True, and then re-deployed with - auto_delete_objects=False, all the objects in the bucket + Overview: if a stack is deployed with an S3 bucket with + auto_delete_objects=True, and then re-deployed with + auto_delete_objects=False, all the objects in the bucket will be deleted. Affected versions: framework: <=2.15.0 >=2.10.0 diff --git a/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml b/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml index 15d7a22f1edfd..d4f674dfa2cac 100644 --- a/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml +++ b/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml @@ -453,6 +453,8 @@ Resources: - cloudformation:DeleteStack - cloudformation:UpdateTerminationProtection - sts:GetCallerIdentity + # `cdk import` + - cloudformation:GetTemplateSummary Resource: "*" Effect: Allow - Sid: CliStagingBucket @@ -507,7 +509,7 @@ Resources: Type: String Name: Fn::Sub: '/cdk-bootstrap/${Qualifier}/version' - Value: '11' + Value: '12' Outputs: BucketName: Description: The name of the S3 bucket owned by the CDK toolkit stack diff --git a/packages/aws-cdk/lib/api/cloudformation-deployments.ts b/packages/aws-cdk/lib/api/cloudformation-deployments.ts index ebf40bbb7442b..5594c71a42630 100644 --- a/packages/aws-cdk/lib/api/cloudformation-deployments.ts +++ b/packages/aws-cdk/lib/api/cloudformation-deployments.ts @@ -6,10 +6,10 @@ import { publishAssets } from '../util/asset-publishing'; import { Mode } from './aws-auth/credentials'; import { ISDK } from './aws-auth/sdk'; import { SdkProvider } from './aws-auth/sdk-provider'; -import { deployStack, DeployStackResult, destroyStack } from './deploy-stack'; +import { deployStack, DeployStackResult, destroyStack, makeBodyParameterAndUpload } from './deploy-stack'; import { loadCurrentTemplateWithNestedStacks, loadCurrentTemplate } from './nested-stack-helpers'; import { ToolkitInfo } from './toolkit-info'; -import { CloudFormationStack, Template } from './util/cloudformation'; +import { CloudFormationStack, Template, ResourcesToImport, ResourceIdentifierSummaries } from './util/cloudformation'; import { StackActivityProgress } from './util/cloudformation/stack-activity-monitor'; import { replaceEnvPlaceholders } from './util/placeholders'; @@ -224,6 +224,18 @@ export interface DeployStackOptions { * @default - nothing extra is appended to the User-Agent header */ readonly extraUserAgent?: string; + + /** + * List of existing resources to be IMPORTED into the stack, instead of being CREATED + */ + readonly resourcesToImport?: ResourcesToImport; + + /** + * If present, use this given template instead of the stored one + * + * @default - Use the stored template + */ + readonly overrideTemplate?: any; } export interface DestroyStackOptions { @@ -280,23 +292,52 @@ export class CloudFormationDeployments { } public async readCurrentTemplateWithNestedStacks(rootStackArtifact: cxapi.CloudFormationStackArtifact): Promise