Integ test

Author: otaviomacedo

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

@@ -502,6 +502,17 @@ class DriftableStack extends cdk.Stack {
   }
 }
 
+class EarlyValidationStack extends cdk.Stack {
+  constructor(parent, id, props) {
+    super(parent, id, props);
+
+    new s3.Bucket(this, 'MyBucket', {
+      bucketName: process.env.BUCKET_NAME,
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+    });
+  }
+}
+
 class IamRolesStack extends cdk.Stack {
   constructor(parent, id, props) {
     super(parent, id, props);
@@ -971,6 +982,9 @@ switch (stackSet) {
     new MetadataStack(app, `${stackPrefix}-metadata`);
 
     new DriftableStack(app, `${stackPrefix}-driftable`);
+
+    new EarlyValidationStack(app, `${stackPrefix}-early-validation-stack1`);
+    new EarlyValidationStack(app, `${stackPrefix}-early-validation-stack2`);
     break;
 
   case 'stage-using-context':

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

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'deploy - early validation error',
+  withDefaultFixture(async (fixture) => {
+    const bucketName = randomUUID();
+
+    // First, deploy a stack that creates a bucket with a custom name,
+    // which we expect to succeed
+    await fixture.cdkDeploy('early-validation-stack1', {
+      modEnv: {
+        BUCKET_NAME: bucketName,
+      },
+    });
+
+    // Then deploy a different instance of the stack, that creates another
+    // bucket with the same name, to induce an early validation error
+    const stdErr = await fixture.cdkDeploy('early-validation-stack2', {
+      modEnv: {
+        BUCKET_NAME: bucketName,
+      },
+      allowErrExit: true,
+    });
+
+    expect(stdErr).toContain(`Resource of type 'AWS::S3::Bucket' with identifier '${bucketName}' already exists`,
+    );
+  }),
+);
+

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

@@ -5,10 +5,23 @@ import { ToolkitError } from '../../toolkit/toolkit-error';
 import type { SDK } from '../aws-auth/sdk';
 import type { EnvironmentResources } from '../environment/index';
 
+/**
+ * Reports early validation failures from CloudFormation ChangeSets. To determine what the actual error is
+ * it needs to call the `DescribeEvents` API, and therefore the deployment role in the bootstrap bucket
+ * must have permissions to call that API. This permission was introduced in version 30 of the bootstrap template.
+ * If the bootstrap stack is older than that, a special error message is thrown to instruct the user to
+ * re-bootstrap.
+ */
 export class EarlyValidationReporter implements ValidationReporter {
   constructor(private readonly sdk: SDK, private readonly environmentResources: EnvironmentResources) {
   }
 
+  /**
+   * Checks whether the ChangeSet failed early validation, and if so, throw an error. Otherwise, do nothing.
+   * @param description - the ChangeSet description, resulting from the call to CloudFormation's DescribeChangeSet API
+   * @param changeSetName - the name of the ChangeSet
+   * @param stackName - the name of the stack
+   */
   public async check(description: DescribeChangeSetCommandOutput, changeSetName: string, stackName: string) {
     if (description.Status === ChangeSetStatus.FAILED && description.StatusReason?.includes('AWS::EarlyValidation')) {
       await this.checkBootstrapVersion();
@@ -40,7 +53,7 @@ export class EarlyValidationReporter implements ValidationReporter {
       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.`,
+          `To see details about these errors, re-bootstrap your environment with 'cdk bootstrap ${env}', and run 'cdk deploy' again.`,
       );
     }
   }