WIP

Author: otaviomacedo

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

@@ -100,7 +100,7 @@ import type {
   DescribeStackResourceDriftsCommandInput,
   ExecuteStackRefactorCommandInput,
   DescribeStackRefactorCommandInput,
-  CreateStackRefactorCommandOutput, ExecuteStackRefactorCommandOutput,
+  CreateStackRefactorCommandOutput, ExecuteStackRefactorCommandOutput, DescribeEventsCommandOutput, DescribeEventsCommandInput,
 } from '@aws-sdk/client-cloudformation';
 import {
   paginateListStacks,
@@ -113,6 +113,7 @@ import {
   DeleteChangeSetCommand,
   DeleteGeneratedTemplateCommand,
   DeleteStackCommand,
+  DescribeEventsCommand,
   DescribeChangeSetCommand,
   DescribeGeneratedTemplateCommand,
   DescribeResourceScanCommand,
@@ -434,6 +435,7 @@ export interface ICloudFormationClient {
   deleteChangeSet(input: DeleteChangeSetCommandInput): Promise<DeleteChangeSetCommandOutput>;
   deleteGeneratedTemplate(input: DeleteGeneratedTemplateCommandInput): Promise<DeleteGeneratedTemplateCommandOutput>;
   deleteStack(input: DeleteStackCommandInput): Promise<DeleteStackCommandOutput>;
+  describeEvents(input: DescribeEventsCommandInput): Promise<DescribeEventsCommandOutput>;
   describeChangeSet(input: DescribeChangeSetCommandInput): Promise<DescribeChangeSetCommandOutput>;
   describeGeneratedTemplate(
     input: DescribeGeneratedTemplateCommandInput,
@@ -710,6 +712,8 @@ export class SDK {
         client.send(new DetectStackDriftCommand(input)),
       detectStackResourceDrift: (input: DetectStackResourceDriftCommandInput): Promise<DetectStackResourceDriftCommandOutput> =>
         client.send(new DetectStackResourceDriftCommand(input)),
+      describeEvents: (input: DescribeEventsCommandInput): Promise<DescribeEventsCommandOutput> =>
+        client.send(new DescribeEventsCommand(input)),
       describeChangeSet: (input: DescribeChangeSetCommandInput): Promise<DescribeChangeSetCommandOutput> =>
         client.send(new DescribeChangeSetCommand(input)),
       describeGeneratedTemplate: (

packages/@aws-cdk/toolkit-lib/lib/api/deployments/cfn-api.ts

@@ -21,6 +21,10 @@ import { CloudFormationStack, makeBodyParameter } from '../cloudformation';
 import type { IoHelper } from '../io/private';
 import type { ResourcesToImport } from '../resource-import';
 
+export interface ValidationReporter {
+  check(description: DescribeChangeSetCommandOutput, changeSetName: string, stackName: string): Promise<void>;
+}
+
 /**
  * Describe a changeset in CloudFormation, regardless of its current state.
  *
@@ -103,7 +107,7 @@ export async function waitForChangeSet(
   ioHelper: IoHelper,
   stackName: string,
   changeSetName: string,
-  { fetchAll }: { fetchAll: boolean },
+  { fetchAll, validationReporter }: { fetchAll: boolean; validationReporter?: ValidationReporter },
 ): Promise<DescribeChangeSetCommandOutput> {
   await ioHelper.defaults.debug(format('Waiting for changeset %s on stack %s to finish creating...', changeSetName, stackName));
   const ret = await waitFor(async () => {
@@ -121,6 +125,8 @@ export async function waitForChangeSet(
       return description;
     }
 
+    await validationReporter?.check(description, changeSetName, stackName);
+
     // eslint-disable-next-line @stylistic/max-len
     throw new ToolkitError(
       `Failed to create ChangeSet ${changeSetName} on ${stackName}: ${description.Status || 'NO_STATUS'}, ${description.StatusReason || 'no reason provided'}`,

packages/@aws-cdk/toolkit-lib/lib/api/deployments/deploy-stack.ts

@@ -32,12 +32,13 @@ import { formatErrorMessage } from '../../util';
 import type { SDK, SdkProvider, ICloudFormationClient } from '../aws-auth/private';
 import type { TemplateBodyParameter } from '../cloudformation';
 import { makeBodyParameter, CfnEvaluationException, CloudFormationStack } from '../cloudformation';
-import type { EnvironmentResources, StringWithoutPlaceholders } from '../environment';
+import { EnvironmentResources, EnvironmentResourcesRegistry, StringWithoutPlaceholders } from '../environment';
 import { HotswapPropertyOverrides, HotswapMode, ICON, createHotswapPropertyOverrides } from '../hotswap/common';
 import { tryHotswapDeployment } from '../hotswap/hotswap-deployments';
 import type { IoHelper } from '../io/private';
 import type { ResourcesToImport } from '../resource-import';
 import { StackActivityMonitor } from '../stack-events';
+import { EarlyValidationReporter } from './early-validation';
 
 export interface DeployStackOptions {
   /**
@@ -511,8 +512,12 @@ class FullCloudFormationDeployment {
 
     await this.ioHelper.defaults.debug(format('Initiated creation of changeset: %s; waiting for it to finish creating...', changeSet.Id));
     // Fetching all pages if we'll execute, so we can have the correct change count when monitoring.
+    const environmentResources = new EnvironmentResourcesRegistry()
+      .for(this.options.resolvedEnvironment, this.options.sdk, this.ioHelper);
+    const validationReporter = new EarlyValidationReporter(this.options.sdk, environmentResources);
     return waitForChangeSet(this.cfn, this.ioHelper, this.stackName, changeSetName, {
       fetchAll: willExecute,
+      validationReporter,
     });
   }
 

packages/@aws-cdk/toolkit-lib/lib/api/deployments/early-validation.ts

@@ -0,0 +1,47 @@
+import type { DescribeChangeSetCommandOutput } from '@aws-sdk/client-cloudformation';
+import { ChangeSetStatus, ValidationStatus } from '@aws-sdk/client-cloudformation';
+import type { ValidationReporter } from './cfn-api';
+import { ToolkitError } from '../../toolkit/toolkit-error';
+import type { SDK } from '../aws-auth/sdk';
+import type { EnvironmentResources } from '../environment/index';
+
+export class EarlyValidationReporter implements ValidationReporter {
+  constructor(private readonly sdk: SDK, private readonly environmentResources: EnvironmentResources) {
+  }
+
+  public async check(description: DescribeChangeSetCommandOutput, changeSetName: string, stackName: string) {
+    if (description.Status === ChangeSetStatus.FAILED && description.StatusReason?.includes('AWS::EarlyValidation')) {
+      await this.checkBootstrapVersion();
+      const eventsOutput = await this.sdk.cloudFormation().describeEvents({
+        ChangeSetName: changeSetName,
+        StackName: stackName,
+      });
+
+      const failures = (eventsOutput.OperationEvents ?? [])
+        .filter((event) => event.ValidationStatus === ValidationStatus.FAILED)
+        .map((event) => `  - ${event.ValidationStatusReason} (at ${event.ValidationPath})`)
+        .join('\n');
+
+      const message = `ChangeSet '${changeSetName}' on stack '${stackName}' failed early validation:\n${failures}`;
+      throw new ToolkitError(message);
+    }
+  }
+
+  private async checkBootstrapVersion() {
+    const environment = this.environmentResources.environment;
+    let bootstrapVersion: number | undefined = undefined;
+    try {
+      // Try to get the bootstrap version
+      bootstrapVersion = (await this.environmentResources.lookupToolkit()).version;
+    } catch (e) {
+      // But if we can't, keep going. Maybe we can still succeed.
+    }
+    if (bootstrapVersion != null && bootstrapVersion < 30) {
+      const env = `aws://${environment.account}/${environment.region}`;
+      throw new ToolkitError(
+        'While creating the change set, CloudFormation detected errors in the generated templates.\n' +
+        `To see details about these errors, re-bootstrap your environment with 'cdk bootstrap ${env}', and run 'cdk deploy' again.`,
+      );
+    }
+  }
+}

packages/@aws-cdk/toolkit-lib/test/api/deployments/deploy-stack.test.ts

@@ -7,6 +7,7 @@ import {
   DeleteChangeSetCommand,
   DeleteStackCommand,
   DescribeChangeSetCommand,
+  DescribeEventsCommand,
   DescribeStacksCommand,
   ExecuteChangeSetCommand,
   type ExecuteChangeSetCommandInput,
@@ -763,6 +764,30 @@ test('deployStack reports no change if describeChangeSet returns specific error'
   expect(deployResult.type === 'did-deploy-stack' && deployResult.noOp).toEqual(true);
 });
 
+test('deployStack throws error in case of early validation failures', async () => {
+  mockCloudFormationClient.on(DescribeChangeSetCommand).resolvesOnce({
+    Status: ChangeSetStatus.FAILED,
+    StatusReason: '(AWS::EarlyValidation::SomeError). Blah blah blah.',
+  });
+
+  mockCloudFormationClient.on(DescribeEventsCommand).resolves({
+    OperationEvents: [
+      {
+        ValidationStatus: 'FAILED',
+        ValidationStatusReason: 'Resource already exists',
+        ValidationPath: 'Resources/MyResource',
+      },
+    ],
+  });
+
+  await expect(
+    testDeployStack({
+      ...standardDeployStackArguments(),
+    }),
+  ).rejects.toThrow(`While creating the change set, CloudFormation detected errors in the generated templates.
+To see details about these errors, re-bootstrap your environment with 'cdk bootstrap aws://123456789/bermuda-triangle-1337', and run 'cdk deploy' again.`);
+});
+
 test('deploy not skipped if template did not change but one tag removed', async () => {
   // GIVEN
   mockCloudFormationClient.on(DescribeStacksCommand).resolves({

packages/@aws-cdk/toolkit-lib/test/api/deployments/early-validation.test.ts

@@ -0,0 +1,87 @@
+import { ChangeSetStatus } from '@aws-sdk/client-cloudformation';
+import { EarlyValidationReporter } from '../../../lib/api/deployments/early-validation';
+
+describe('EarlyValidationReporter', () => {
+  let mockSdk: any;
+  let mockEnvironmentResources: any;
+  let reporter: EarlyValidationReporter;
+
+  beforeEach(() => {
+    mockSdk = {
+      cloudFormation: jest.fn().mockReturnValue({
+        describeEvents: jest.fn(),
+      }),
+    };
+    mockEnvironmentResources = {
+      environment: { account: '123456789012', region: 'us-east-1' },
+      lookupToolkit: jest.fn(),
+    };
+    reporter = new EarlyValidationReporter(mockSdk, mockEnvironmentResources);
+  });
+
+  it('does not throw when ChangeSet status is FAILED but reason is not AWS::EarlyValidation', async () => {
+    const description = {
+      $metadata: {},
+      Status: ChangeSetStatus.FAILED,
+      StatusReason: 'Some other reason',
+    };
+    const changeSetName = 'test-change-set';
+    const stackName = 'test-stack';
+
+    await expect(reporter.check(description, changeSetName, stackName)).resolves.not.toThrow();
+  });
+
+  it('does not throw when ChangeSet status is undefined', async () => {
+    const description = {
+      $metadata: {},
+      Status: undefined,
+      StatusReason: undefined,
+    };
+    const changeSetName = 'test-change-set';
+    const stackName = 'test-stack';
+
+    await expect(reporter.check(description, changeSetName, stackName)).resolves.not.toThrow();
+  });
+
+  it('throws when ChangeSet status is FAILED due to AWS::EarlyValidation', async () => {
+    const description = {
+      $metadata: {},
+      Status: ChangeSetStatus.FAILED,
+      StatusReason: 'The following resource(s) failed to create: [MyResource] (AWS::EarlyValidation).',
+    };
+    const changeSetName = 'test-change-set';
+    const stackName = 'test-stack';
+
+    mockSdk.cloudFormation().describeEvents.mockResolvedValue({
+      OperationEvents: [
+        {
+          ValidationStatus: 'FAILED',
+          ValidationStatusReason: 'Resource already exists',
+          ValidationPath: 'Resources/MyResource',
+        },
+      ],
+    });
+
+    await expect(reporter.check(description, changeSetName, stackName)).rejects.toThrow(
+      `ChangeSet 'test-change-set' on stack 'test-stack' failed early validation:
+  - Resource already exists (at Resources/MyResource)`,
+    );
+  });
+
+  it('throws with bootstrap version less than 30', async () => {
+    const description = {
+      $metadata: {},
+      Status: ChangeSetStatus.FAILED,
+      StatusReason: 'The following resource(s) failed to create: [MyResource] (AWS::EarlyValidation).',
+    };
+    const changeSetName = 'test-change-set';
+    const stackName = 'test-stack';
+
+    mockEnvironmentResources.lookupToolkit.mockResolvedValue({ version: 29 });
+
+    await expect(reporter.check(description, changeSetName, stackName)).rejects.toThrow(
+      `While creating the change set, CloudFormation detected errors in the generated templates.
+To see details about these errors, re-bootstrap your environment with 'cdk bootstrap aws://123456789012/us-east-1', and run 'cdk deploy' again.`,
+    );
+  });
+});

packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml

@@ -631,6 +631,7 @@ Resources:
                   - cloudformation:DeleteChangeSet
                   - cloudformation:DescribeChangeSet
                   - cloudformation:DescribeStacks
+                  - cloudformation:DescribeEvents
                   - cloudformation:ExecuteChangeSet
                   - cloudformation:CreateStack
                   - cloudformation:UpdateStack
@@ -814,7 +815,7 @@ Resources:
       Name:
         Fn::Sub: '/cdk-bootstrap/${Qualifier}/version'
       # Also update this value below (see comment there)
-      Value: '29'
+      Value: '30'
 Outputs:
   BucketName:
     Description: The name of the S3 bucket owned by the CDK toolkit stack
@@ -849,4 +850,4 @@ Outputs:
     # {Fn::GetAtt} on an SSM Parameter is eventually consistent, and can fail with "parameter
     # doesn't exist" even after just having been created. To reduce our deploy failure rate, we
     # duplicate the value here and use a build-time test to ensure the two values are the same.
-    Value: '29'
+    Value: '30'