feat(cli,toolkit-lib): drift detection via cdk drift and toolkit.drift()

packages/@aws-cdk-testing/cli-integ/resources/cdk-apps/app/app.js

@@ -475,6 +475,33 @@ class LambdaStack extends cdk.Stack {
   }
 }
 
+class DriftableStack extends cdk.Stack {
+  constructor(parent, id, props) {
+    const synthesizer = parent.node.tryGetContext('legacySynth') === 'true' ?
+      new LegacyStackSynthesizer({
+        fileAssetsBucketName: parent.node.tryGetContext('bootstrapBucket'),
+      })
+      : new DefaultStackSynthesizer({
+        fileAssetsBucketName: parent.node.tryGetContext('bootstrapBucket'),
+      })
+    super(parent, id, {
+      ...props,
+      synthesizer: synthesizer,
+    });
+
+    const fn = new lambda.Function(this, 'my-function', {
+      code: lambda.Code.asset(path.join(__dirname, 'lambda')),
+      runtime: lambda.Runtime.NODEJS_LATEST,
+      handler: 'index.handler',
+      description: 'This is my function!',
+      timeout: cdk.Duration.seconds(5),
+      memorySize: 128
+    });
+
+    new cdk.CfnOutput(this, 'FunctionArn', { value: fn.functionArn });
+  }
+}
+
 class IamRolesStack extends cdk.Stack {
   constructor(parent, id, props) {
     super(parent, id, props);
@@ -942,6 +969,8 @@ switch (stackSet) {
     new BundlingStage(app, `${stackPrefix}-bundling-stage`);
 
     new MetadataStack(app, `${stackPrefix}-metadata`);
+
+    new DriftableStack(app, `${stackPrefix}-driftable`);
     break;
 
   case 'stage-using-context':

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/drift/cdk-cdk-drift---fail-throws-when-drift-is-detected.integtest.ts

@@ -0,0 +1,77 @@
+import { DescribeStackResourcesCommand } from '@aws-sdk/client-cloudformation';
+import { GetFunctionCommand, UpdateFunctionConfigurationCommand } from '@aws-sdk/client-lambda';
+import { integTest, sleep, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'cdk drift --fail throws when drift is detected',
+  withDefaultFixture(async (fixture) => {
+    await fixture.cdkDeploy('driftable', {});
+
+    // Assert that, right after deploying, there is no drift (because we just deployed it)
+    const drift = await fixture.cdk(['drift', '--fail', fixture.fullStackName('driftable')], { verbose: false });
+
+    expect(drift).toContain('No drift detected');
+
+    // Get the Lambda, we want to now make it drift
+    const response = await fixture.aws.cloudFormation.send(
+      new DescribeStackResourcesCommand({
+        StackName: fixture.fullStackName('driftable'),
+      }),
+    );
+    const lambdaResource = response.StackResources?.find(
+      resource => resource.ResourceType === 'AWS::Lambda::Function',
+    );
+    if (!lambdaResource || !lambdaResource.PhysicalResourceId) {
+      throw new Error('Could not find Lambda function in stack resources');
+    }
+    const functionName = lambdaResource.PhysicalResourceId;
+
+    // Update the Lambda function, introducing drift
+    await fixture.aws.lambda.send(
+      new UpdateFunctionConfigurationCommand({
+        FunctionName: functionName,
+        Description: 'I\'m slowly drifting (drifting away)',
+      }),
+    );
+
+    // Wait for the stack update to complete
+    await waitForLambdaUpdateComplete(fixture, functionName);
+
+    await expect(
+      fixture.cdk(['drift', '--fail', fixture.fullStackName('driftable')], { verbose: false }),
+    ).rejects.toThrow('exited with error');
+  }),
+);
+
+async function waitForLambdaUpdateComplete(fixture: any, functionName: string): Promise<void> {
+  const delaySeconds = 5;
+  const timeout = 30_000; // timeout after 30s
+  const deadline = Date.now() + timeout;
+
+  while (true) {
+    const response = await fixture.aws.lambda.send(
+      new GetFunctionCommand({
+        FunctionName: functionName,
+      }),
+    );
+
+    const lastUpdateStatus = response.Configuration?.LastUpdateStatus;
+
+    if (lastUpdateStatus === 'Successful') {
+      return; // Update completed successfully
+    }
+
+    if (lastUpdateStatus === 'Failed') {
+      throw new Error('Lambda function update failed');
+    }
+
+    if (Date.now() > deadline) {
+      throw new Error(`Timed out after ${timeout / 1000} seconds.`);
+    }
+
+    // Wait before checking again
+    await sleep(delaySeconds * 1000);
+  }
+}

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/drift/cdk-cdk-drift---verbose-shows-unchecked-resources.integtest.ts

@@ -0,0 +1,19 @@
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'cdk drift --verbose shows unchecked resources',
+  withDefaultFixture(async (fixture) => {
+    await fixture.cdkDeploy('define-vpc', { modEnv: { ENABLE_VPC_TESTING: 'DEFINE' } });
+
+    // Assert that there's no drift when we deploy it, but there should be
+    // unchecked resources, as there are some EC2 connection resources
+    // (e.g. SubnetRouteTableAssociation) that do not support drift detection
+    const drift = await fixture.cdk(['drift', '--verbose', fixture.fullStackName('define-vpc')], { modEnv: { ENABLE_VPC_TESTING: 'DEFINE' } });
+
+    expect(drift).toMatch(/Stack.*define-vpc/); // cant just .toContain because of formatting
+    expect(drift).toContain('No drift detected');
+    expect(drift).toContain('(3 unchecked)'); // 2 SubnetRouteTableAssociations, 1 VPCGatewayAttachment
+  }),
+);

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

@@ -0,0 +1,96 @@
+import { DescribeStackResourcesCommand } from '@aws-sdk/client-cloudformation';
+import { GetFunctionCommand, UpdateFunctionConfigurationCommand } from '@aws-sdk/client-lambda';
+import { integTest, sleep, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'cdk drift',
+  withDefaultFixture(async (fixture) => {
+    await fixture.cdkDeploy('driftable', {});
+
+    // Assert that, right after deploying, there is no drift (because we just deployed it)
+    const drift = await fixture.cdk(['drift', fixture.fullStackName('driftable')], { verbose: false });
+
+    expect(drift).toMatch(/Stack.*driftable/); // can't just .toContain because of formatting
+    expect(drift).toContain('No drift detected');
+    expect(drift).toContain('✨  Number of resources with drift: 0');
+    expect(drift).not.toContain('unchecked'); // should not see unchecked resources unless verbose
+
+    // Get the Lambda, we want to now make it drift
+    const response = await fixture.aws.cloudFormation.send(
+      new DescribeStackResourcesCommand({
+        StackName: fixture.fullStackName('driftable'),
+      }),
+    );
+    const lambdaResource = response.StackResources?.find(
+      resource => resource.ResourceType === 'AWS::Lambda::Function',
+    );
+    if (!lambdaResource || !lambdaResource.PhysicalResourceId) {
+      throw new Error('Could not find Lambda function in stack resources');
+    }
+    const functionName = lambdaResource.PhysicalResourceId;
+
+    // Update the Lambda function, introducing drift
+    await fixture.aws.lambda.send(
+      new UpdateFunctionConfigurationCommand({
+        FunctionName: functionName,
+        Description: 'I\'m slowly drifting (drifting away)',
+      }),
+    );
+
+    // Wait for the stack update to complete
+    await waitForLambdaUpdateComplete(fixture, functionName);
+
+    const driftAfterModification = await fixture.cdk(['drift', fixture.fullStackName('driftable')], { verbose: false });
+
+    const expectedMatches = [
+      /Stack.*driftable/,
+      /[-].*This is my function!/m,
+      /[+].*I'm slowly drifting \(drifting away\)/m,
+    ];
+    const expectedSubstrings = [
+      '1 resource has drifted', // num resources drifted
+      '✨  Number of resources with drift: 1',
+      'AWS::Lambda::Function', // the lambda should be marked drifted
+      '/Description', // the resources that have drifted
+    ];
+    for (const expectedMatch of expectedMatches) {
+      expect(driftAfterModification).toMatch(expectedMatch);
+    }
+    for (const expectedSubstring of expectedSubstrings) {
+      expect(driftAfterModification).toContain(expectedSubstring);
+    }
+  }),
+);
+
+async function waitForLambdaUpdateComplete(fixture: any, functionName: string): Promise<void> {
+  const delaySeconds = 5;
+  const timeout = 30_000; // timeout after 30s
+  const deadline = Date.now() + timeout;
+
+  while (true) {
+    const response = await fixture.aws.lambda.send(
+      new GetFunctionCommand({
+        FunctionName: functionName,
+      }),
+    );
+
+    const lastUpdateStatus = response.Configuration?.LastUpdateStatus;
+
+    if (lastUpdateStatus === 'Successful') {
+      return; // Update completed successfully
+    }
+
+    if (lastUpdateStatus === 'Failed') {
+      throw new Error('Lambda function update failed');
+    }
+
+    if (Date.now() > deadline) {
+      throw new Error(`Timed out after ${timeout / 1000} seconds.`);
+    }
+
+    // Wait before checking again
+    await sleep(delaySeconds * 1000);
+  }
+}

packages/@aws-cdk/toolkit-lib/docs/message-registry.md

@@ -72,6 +72,8 @@ Please let us know by [opening an issue](https://github.com/aws/aws-cdk-cli/issu
 | `CDK_TOOLKIT_E3900` | Resource import failed | `error` | {@link ErrorPayload} |
 | `CDK_TOOLKIT_I4000` | Diff stacks is starting | `trace` | {@link StackSelectionDetails} |
 | `CDK_TOOLKIT_I4001` | Output of the diff command | `info` | {@link DiffResult} |
+| `CDK_TOOLKIT_I4590` | Results of the drift command | `result` | {@link DriftResultPayload} |
+| `CDK_TOOLKIT_I4591` | Missing drift result fort a stack. | `warn` | {@link SingleStack} |
 | `CDK_TOOLKIT_I5000` | Provides deployment times | `info` | {@link Duration} |
 | `CDK_TOOLKIT_I5001` | Provides total time in deploy action, including synth and rollback | `info` | {@link Duration} |
 | `CDK_TOOLKIT_I5002` | Provides time for resource migration | `info` | {@link Duration} |

packages/@aws-cdk/toolkit-lib/lib/actions/drift/index.ts

@@ -0,0 +1,58 @@
+import type { StackSelector } from '../../api/cloud-assembly';
+
+export interface DriftOptions {
+  /**
+   * Criteria for selecting stacks to check for drift
+   */
+  readonly stacks: StackSelector;
+}
+
+/**
+ * The different types of drift as formatted drift output
+ *
+ * A missing type implies no drift of this type.
+ * If no drift was detected at all, all will be missing.
+ */
+export interface FormattedDrift {
+  /**
+   * Resources that have not changed
+   */
+  readonly unchanged?: string;
+
+  /**
+   * Resources that were not checked for drift
+   */
+  readonly unchecked?: string;
+
+  /**
+   * Resources with drift
+   */
+  readonly modified?: string;
+
+  /**
+   * Resources that have been deleted (drift)
+   */
+  readonly deleted?: string;
+}
+
+/**
+ * Combined drift for selected stacks of the app
+ */
+export interface DriftResult {
+  /**
+   * Number of resources with drift. If undefined, then an error occurred
+   * and resources were not properly checked for drift.
+   */
+  readonly numResourcesWithDrift: number;
+
+  /**
+   * How many resources were not checked for drift. If undefined, then an
+   * error occurred and resources were not properly checked for drift.
+   */
+  readonly numResourcesUnchecked: number;
+
+  /**
+   * Complete formatted drift
+   */
+  readonly formattedDrift: FormattedDrift;
+}

packages/@aws-cdk/toolkit-lib/lib/actions/index.ts

@@ -2,6 +2,7 @@ export * from './bootstrap';
 export * from './deploy';
 export * from './destroy';
 export * from './diff';
+export * from './drift';
 export * from './list';
 export * from './refactor';
 export * from './rollback';

packages/@aws-cdk/toolkit-lib/lib/api/aws-auth/sdk.ts

@@ -89,6 +89,14 @@ import type {
   UpdateTerminationProtectionCommandInput,
   UpdateTerminationProtectionCommandOutput,
   StackSummary,
+  DescribeStackDriftDetectionStatusCommandInput,
+  DescribeStackDriftDetectionStatusCommandOutput,
+  DescribeStackResourceDriftsCommandOutput,
+  DetectStackDriftCommandInput,
+  DetectStackDriftCommandOutput,
+  DetectStackResourceDriftCommandInput,
+  DetectStackResourceDriftCommandOutput,
+  DescribeStackResourceDriftsCommandInput,
 } from '@aws-sdk/client-cloudformation';
 import {
   paginateListStacks,
@@ -120,6 +128,10 @@ import {
   StartResourceScanCommand,
   UpdateStackCommand,
   UpdateTerminationProtectionCommand,
+  DescribeStackDriftDetectionStatusCommand,
+  DescribeStackResourceDriftsCommand,
+  DetectStackDriftCommand,
+  DetectStackResourceDriftCommand,
 } from '@aws-sdk/client-cloudformation';
 import type {
   FilterLogEventsCommandInput,
@@ -419,8 +431,12 @@ export interface ICloudFormationClient {
     input: DescribeGeneratedTemplateCommandInput,
   ): Promise<DescribeGeneratedTemplateCommandOutput>;
   describeResourceScan(input: DescribeResourceScanCommandInput): Promise<DescribeResourceScanCommandOutput>;
+  describeStackDriftDetectionStatus(input: DescribeStackDriftDetectionStatusCommandInput): Promise<DescribeStackDriftDetectionStatusCommandOutput>;
   describeStacks(input: DescribeStacksCommandInput): Promise<DescribeStacksCommandOutput>;
+  describeStackResourceDrifts(input: DescribeStackResourceDriftsCommandInput): Promise<DescribeStackResourceDriftsCommandOutput>;
   describeStackResources(input: DescribeStackResourcesCommandInput): Promise<DescribeStackResourcesCommandOutput>;
+  detectStackDrift(input: DetectStackDriftCommandInput): Promise<DetectStackDriftCommandOutput>;
+  detectStackResourceDrift(input: DetectStackResourceDriftCommandInput): Promise<DetectStackResourceDriftCommandOutput>;
   executeChangeSet(input: ExecuteChangeSetCommandInput): Promise<ExecuteChangeSetCommandOutput>;
   getGeneratedTemplate(input: GetGeneratedTemplateCommandInput): Promise<GetGeneratedTemplateCommandOutput>;
   getTemplate(input: GetTemplateCommandInput): Promise<GetTemplateCommandOutput>;
@@ -681,13 +697,21 @@ export class SDK {
       ): Promise<DeleteGeneratedTemplateCommandOutput> => client.send(new DeleteGeneratedTemplateCommand(input)),
       deleteStack: (input: DeleteStackCommandInput): Promise<DeleteStackCommandOutput> =>
         client.send(new DeleteStackCommand(input)),
+      detectStackDrift: (input: DetectStackDriftCommandInput): Promise<DetectStackDriftCommandOutput> =>
+        client.send(new DetectStackDriftCommand(input)),
+      detectStackResourceDrift: (input: DetectStackResourceDriftCommandInput): Promise<DetectStackResourceDriftCommandOutput> =>
+        client.send(new DetectStackResourceDriftCommand(input)),
       describeChangeSet: (input: DescribeChangeSetCommandInput): Promise<DescribeChangeSetCommandOutput> =>
         client.send(new DescribeChangeSetCommand(input)),
       describeGeneratedTemplate: (
         input: DescribeGeneratedTemplateCommandInput,
       ): Promise<DescribeGeneratedTemplateCommandOutput> => client.send(new DescribeGeneratedTemplateCommand(input)),
       describeResourceScan: (input: DescribeResourceScanCommandInput): Promise<DescribeResourceScanCommandOutput> =>
         client.send(new DescribeResourceScanCommand(input)),
+      describeStackDriftDetectionStatus: (input: DescribeStackDriftDetectionStatusCommandInput):
+      Promise<DescribeStackDriftDetectionStatusCommandOutput> => client.send(new DescribeStackDriftDetectionStatusCommand(input)),
+      describeStackResourceDrifts: (input: DescribeStackResourceDriftsCommandInput): Promise<DescribeStackResourceDriftsCommandOutput> =>
+        client.send(new DescribeStackResourceDriftsCommand(input)),
       describeStacks: (input: DescribeStacksCommandInput): Promise<DescribeStacksCommandOutput> =>
         client.send(new DescribeStacksCommand(input)),
       describeStackResources: (input: DescribeStackResourcesCommandInput): Promise<DescribeStackResourcesCommandOutput> =>

packages/@aws-cdk/toolkit-lib/lib/api/diff/diff-formatter.ts

@@ -56,7 +56,7 @@ interface DiffFormatterProps {
 }
 
 /**
- * PRoperties specific to formatting the stack diff
+ * Properties specific to formatting the stack diff
  */
 interface FormatStackDiffOptions {
   /**