feat(cli): support CloudFormation simplified resource import

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/cli.integtest.ts

@@ -280,6 +280,65 @@ integTest('deploy without execute a named change set', withDefaultFixture(async
   expect(changeSets[0].Status).toEqual('CREATE_COMPLETE');
 }));
 
+integTest('deploy with import-existing-resources true', withDefaultFixture(async (fixture) => {
+  const stackArn = await fixture.cdkDeploy('test-2', {
+    options: ['--no-execute', '--import-existing-resources'],
+    captureStderr: false,
+  });
+  // verify that we only deployed a single stack (there's a single ARN in the output)
+  expect(stackArn.split('\n').length).toEqual(1);
+
+  const response = await fixture.aws.cloudFormation('describeStacks', {
+    StackName: stackArn,
+  });
+  expect(response.Stacks?.[0].StackStatus).toEqual('REVIEW_IN_PROGRESS');
+
+  // verify a change set was successfully created
+  // Here, we do not test whether a resource is actually imported, because that is a CloudFormation feature, not a CDK feature.
+  const changeSetResponse = await fixture.aws.cloudFormation('listChangeSets', {
+    StackName: stackArn,
+  });
+  const changeSets = changeSetResponse.Summaries || [];
+  expect(changeSets.length).toEqual(1);
+  expect(changeSets[0].Status).toEqual('CREATE_COMPLETE');
+  expect(changeSets[0].ImportExistingResources).toEqual(true);
+}));
+
+integTest('deploy without import-existing-resources', withDefaultFixture(async (fixture) => {
+  const stackArn = await fixture.cdkDeploy('test-2', {
+    options: ['--no-execute'],
+    captureStderr: false,
+  });
+  // verify that we only deployed a single stack (there's a single ARN in the output)
+  expect(stackArn.split('\n').length).toEqual(1);
+
+  const response = await fixture.aws.cloudFormation('describeStacks', {
+    StackName: stackArn,
+  });
+  expect(response.Stacks?.[0].StackStatus).toEqual('REVIEW_IN_PROGRESS');
+
+  // verify a change set was successfully created and ImportExistingResources = false
+  const changeSetResponse = await fixture.aws.cloudFormation('listChangeSets', {
+    StackName: stackArn,
+  });
+  const changeSets = changeSetResponse.Summaries || [];
+  expect(changeSets.length).toEqual(1);
+  expect(changeSets[0].Status).toEqual('CREATE_COMPLETE');
+  expect(changeSets[0].ImportExistingResources).toEqual(false);
+}));
+
+integTest('deploy with method=direct and import-existing-resources fails', withDefaultFixture(async (fixture) => {
+  const stackName = 'iam-test';
+  await expect(fixture.cdkDeploy(stackName, {
+    options: ['--import-existing-resources', '--method=direct'],
+  })).rejects.toThrow('exited with error');
+
+  // Ensure stack was not deployed
+  await expect(fixture.aws.cloudFormation('describeStacks', {
+    StackName: fixture.fullStackName(stackName),
+  })).rejects.toThrow('does not exist');
+}));
+
 integTest('security related changes without a CLI are expected to fail', withDefaultFixture(async (fixture) => {
   // redirect /dev/null to stdin, which means there will not be tty attached
   // since this stack includes security-related changes, the deployment should

packages/aws-cdk/README.md

@@ -386,6 +386,40 @@ $ cdk deploy --method=prepare-change-set --change-set-name MyChangeSetName
 For more control over when stack changes are deployed, the CDK can generate a
 CloudFormation change set but not execute it.
 
+#### Import existing resources
+
+You can pass the `--import-existing-resources` flag to the `deploy` command:
+
+```console
+$ cdk deploy --import-existing-resources
+```
+
+This allows you to automatically import the resources in your template that already
+exist in your AWS account during CloudFormation deployments.
+With this feature, you can reduce the manual effort of import operations and avoid
+deployment failures because of naming conflicts.
+
+To review which resources are imported or not before actually executing a change set,
+use `--method=prepare-change-set` flag.
+You can inspect the change set created by CDK from the management console or other external tools.
+
+```console
+$ cdk deploy --import-existing-resources --method=prepare-change-set
+```
+
+To enable this feature only for a specific stack, use `--exclusively` flag.
+
+```console
+$ cdk deploy --import-existing-resources --exclusively StackName
+```
+
+This parameter can only import resources that have custom names in templates. 
+For more information, see [name type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html). 
+To import resources that do not accept custom names, such as EC2 instances,
+use the `cdk import` instead. 
+Visit [Bringing existing resources into CloudFormation management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html)
+for more details.
+
 #### Ignore No Stacks
 
 You may have an app with multiple environments, e.g., dev and prod. When starting
@@ -577,6 +611,11 @@ To import an existing resource to a CDK stack, follow the following steps:
 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.
 
+NOTE: You can also import existing resources by `--import-existing-resources` option of `cdk deploy` command.
+This parameter only works for resources that you can set custom physical names,
+such as S3 bucket, DynamoDB table, etc.
+For more information, see [Request Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateChangeSet.html#API_CreateChangeSet_RequestParameters).
+
 #### Limitations
 
 This feature currently has the following limitations:

packages/aws-cdk/lib/api/deploy-stack.ts

@@ -224,6 +224,13 @@ export interface ChangeSetDeploymentMethod {
    * If not provided, a name will be generated automatically.
    */
   readonly changeSetName?: string;
+
+  /**
+   * Indicates if the stack set imports resources that already exist.
+   *
+   * @default false
+   */
+  readonly importExistingResources?: boolean;
 }
 
 export async function deployStack(options: DeployStackOptions): Promise<DeployStackResult> {
@@ -373,7 +380,8 @@ class FullCloudFormationDeployment {
   private async changeSetDeployment(deploymentMethod: ChangeSetDeploymentMethod): Promise<DeployStackResult> {
     const changeSetName = deploymentMethod.changeSetName ?? 'cdk-deploy-change-set';
     const execute = deploymentMethod.execute ?? true;
-    const changeSetDescription = await this.createChangeSet(changeSetName, execute);
+    const importExistingResources = deploymentMethod.importExistingResources ?? false;
+    const changeSetDescription = await this.createChangeSet(changeSetName, execute, importExistingResources);
     await this.updateTerminationProtection();
 
     if (changeSetHasNoChanges(changeSetDescription)) {
@@ -404,7 +412,7 @@ class FullCloudFormationDeployment {
     return this.executeChangeSet(changeSetDescription);
   }
 
-  private async createChangeSet(changeSetName: string, willExecute: boolean) {
+  private async createChangeSet(changeSetName: string, willExecute: boolean, importExistingResources: boolean) {
     await this.cleanupOldChangeset(changeSetName);
 
     debug(`Attempting to create ChangeSet with name ${changeSetName} to ${this.verb} stack ${this.stackName}`);
@@ -416,6 +424,7 @@ class FullCloudFormationDeployment {
       ResourcesToImport: this.options.resourcesToImport,
       Description: `CDK Changeset for execution ${this.uuid}`,
       ClientToken: `create${this.uuid}`,
+      ImportExistingResources: importExistingResources,
       ...this.commonPrepareOptions(),
     }).promise();
 

packages/aws-cdk/lib/cli.ts

@@ -130,6 +130,7 @@ async function parseCommandLineArguments(args: string[]) {
         requiresArg: true,
         desc: 'How to perform the deployment. Direct is a bit faster but lacks progress information',
       })
+      .option('import-existing-resources', { type: 'boolean', desc: 'Indicates if the stack set imports resources that already exist.', default: false })
       .option('force', { alias: 'f', type: 'boolean', desc: 'Always deploy stack even if templates are identical', default: false })
       .option('parameters', { type: 'array', desc: 'Additional parameters passed to CloudFormation at deploy time (STACK:KEY=VALUE)', nargs: 1, requiresArg: true, default: {} })
       .option('outputs-file', { type: 'string', alias: 'O', desc: 'Path to file where stack outputs will be written as JSON', requiresArg: true })
@@ -566,16 +567,19 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
             if (args.changeSetName) {
               throw new Error('--change-set-name cannot be used with method=direct');
             }
+            if (args.importExistingResources) {
+              throw new Error('--import-existing-resources cannot be enabled with method=direct');
+            }
             deploymentMethod = { method: 'direct' };
             break;
           case 'change-set':
-            deploymentMethod = { method: 'change-set', execute: true, changeSetName: args.changeSetName };
+            deploymentMethod = { method: 'change-set', execute: true, changeSetName: args.changeSetName, importExistingResources: args.importExistingResources };
             break;
           case 'prepare-change-set':
-            deploymentMethod = { method: 'change-set', execute: false, changeSetName: args.changeSetName };
+            deploymentMethod = { method: 'change-set', execute: false, changeSetName: args.changeSetName, importExistingResources: args.importExistingResources };
             break;
           case undefined:
-            deploymentMethod = { method: 'change-set', execute: args.execute ?? true, changeSetName: args.changeSetName };
+            deploymentMethod = { method: 'change-set', execute: args.execute ?? true, changeSetName: args.changeSetName, importExistingResources: args.importExistingResources };
             break;
         }
 

packages/aws-cdk/test/api/deploy-stack.test.ts

@@ -880,6 +880,41 @@ describe('disable rollback', () => {
 
 });
 
+describe('import-existing-resources', () => {
+  test('by default, import-existing-resources is disabled', async () => {
+    // WHEN
+    await deployStack({
+      ...standardDeployStackArguments(),
+      deploymentMethod: {
+        method: 'change-set',
+      },
+    });
+
+    // THEN
+    expect(cfnMocks.createChangeSet).toHaveBeenCalledTimes(1);
+    expect(cfnMocks.createChangeSet).toHaveBeenCalledWith(expect.objectContaining({
+      ImportExistingResources: false,
+    }));
+  });
+
+  test('import-existing-resources is enabled', async () => {
+    // WHEN
+    await deployStack({
+      ...standardDeployStackArguments(),
+      deploymentMethod: {
+        method: 'change-set',
+        importExistingResources: true,
+      },
+    });
+
+    // THEN
+    expect(cfnMocks.createChangeSet).toHaveBeenCalledTimes(1);
+    expect(cfnMocks.createChangeSet).toHaveBeenCalledWith(expect.objectContaining({
+      ImportExistingResources: true,
+    }));
+  });
+});
+
 /**
  * Set up the mocks so that it looks like the stack exists to start with
  *