feat(core): configure SNS topics to receive stack events on the Stack construct

packages/@aws-cdk-testing/cli-integ/lib/package-sources/repo-source.ts

@@ -75,13 +75,14 @@ const YARN_MONOREPO_CACHE: Record<string, any> = {};
   *
   * Cached in YARN_MONOREPO_CACHE.
   */
-async function findYarnPackages(root: string): Promise<Record<string, string>> {
+export async function findYarnPackages(root: string): Promise<Record<string, string>> {
   if (!(root in YARN_MONOREPO_CACHE)) {
-    const output: YarnWorkspacesOutput = JSON.parse(await shell(['yarn', 'workspaces', '--silent', 'info'], {
+    const outputDataString: string = JSON.parse(await shell(['yarn', 'workspaces', '--json', 'info'], {
       captureStderr: false,
       cwd: root,
       show: 'error',
-    }));
+    })).data;
+    const output: YarnWorkspacesOutput = JSON.parse(outputDataString);
 
     const ret: Record<string, string> = {};
     for (const [k, v] of Object.entries(output)) {
@@ -96,7 +97,7 @@ async function findYarnPackages(root: string): Promise<Record<string, string>> {
  * Find the root directory of the repo from the current directory
  */
 export async function autoFindRoot() {
-  const found = await findUp('release.json');
+  const found = findUp('release.json');
   if (!found) {
     throw new Error(`Could not determine repository root: 'release.json' not found from ${process.cwd()}`);
   }

packages/@aws-cdk-testing/cli-integ/lib/with-cdk-app.ts

@@ -4,6 +4,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { outputFromStack, AwsClients } from './aws';
 import { TestContext } from './integ-test';
+import { findYarnPackages } from './package-sources/repo-source';
 import { IPackageSource } from './package-sources/source';
 import { packageSourceInSubprocess } from './package-sources/subprocess';
 import { RESOURCES_DIR } from './resources';
@@ -612,6 +613,17 @@ function defined<A>(x: A): x is NonNullable<A> {
  * for Node's dependency lookup mechanism).
  */
 export async function installNpmPackages(fixture: TestFixture, packages: Record<string, string>) {
+  if (process.env.REPO_ROOT) {
+    const monoRepo = await findYarnPackages(process.env.REPO_ROOT);
+
+    // Replace the install target with the physical location of this package
+    for (const key of Object.keys(packages)) {
+      if (key in monoRepo) {
+        packages[key] = monoRepo[key];
+      }
+    }
+  }
+
   fs.writeFileSync(path.join(fixture.integTestDir, 'package.json'), JSON.stringify({
     name: 'cdk-integ-tests',
     private: true,

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

@@ -637,6 +637,13 @@ class BuiltinLambdaStack extends cdk.Stack {
   }
 }
 
+class NotificationArnPropStack extends cdk.Stack {
+  constructor(parent, id, props) {
+    super(parent, id, props);
+    new sns.Topic(this, 'topic');
+  }
+}
+
 const app = new cdk.App({
   context: {
     '@aws-cdk/core:assetHashSalt': process.env.CODEBUILD_BUILD_ID, // Force all assets to be unique, but consistent in one build
@@ -677,6 +684,10 @@ switch (stackSet) {
     new DockerStack(app, `${stackPrefix}-docker`);
     new DockerStackWithCustomFile(app, `${stackPrefix}-docker-with-custom-file`);
 
+    new NotificationArnPropStack(app, `${stackPrefix}-notification-arn-prop`, {
+      notificationArns: [`arn:aws:sns:${defaultEnv.region}:${defaultEnv.account}:${stackPrefix}-test-topic-prop`],
+    });
+
     // SSO stacks
     new SsoInstanceAccessControlConfig(app, `${stackPrefix}-sso-access-control`);
     new SsoAssignment(app, `${stackPrefix}-sso-assignment`);

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

@@ -1,7 +1,7 @@
 import { promises as fs, existsSync } from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { integTest, cloneDirectory, shell, withDefaultFixture, retry, sleep, randomInteger, withSamIntegrationFixture, RESOURCES_DIR, withCDKMigrateFixture, withExtendedTimeoutFixture, randomString } from '../../lib';
+import { integTest, cloneDirectory, shell, withDefaultFixture, retry, sleep, randomInteger, withSamIntegrationFixture, RESOURCES_DIR, withCDKMigrateFixture, withExtendedTimeoutFixture, randomString, withoutBootstrap } from '../../lib';
 
 jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
 
@@ -187,7 +187,10 @@ integTest('context setting', withDefaultFixture(async (fixture) => {
   }
 }));
 
-integTest('context in stage propagates to top', withDefaultFixture(async (fixture) => {
+// bootstrapping also performs synthesis. As it turns out, bootstrap-stage synthesis still causes the lookups to be cached, meaning that the lookup never
+// happens when we actually call `cdk synth --no-lookups`. This results in the error never being thrown, because it never tries to lookup anything.
+// Fix this by not trying to bootstrap; there's no need to bootstrap anyway, since the test never tries to deploy anything.
+integTest('context in stage propagates to top', withoutBootstrap(async (fixture) => {
   await expect(fixture.cdkSynth({
     // This will make it error to prove that the context bubbles up, and also that we can fail on command
     options: ['--no-lookups'],
@@ -466,11 +469,12 @@ integTest('deploy with parameters multi', withDefaultFixture(async (fixture) =>
   );
 }));
 
-integTest('deploy with notification ARN', withDefaultFixture(async (fixture) => {
-  const topicName = `${fixture.stackNamePrefix}-test-topic`;
+integTest('deploy with notification ARN as flag', withDefaultFixture(async (fixture) => {
+  const topicName = `${fixture.stackNamePrefix}-test-topic-flag`;
 
   const response = await fixture.aws.sns('createTopic', { Name: topicName });
   const topicArn = response.TopicArn!;
+
   try {
     await fixture.cdkDeploy('test-2', {
       options: ['--notification-arns', topicArn],
@@ -488,6 +492,27 @@ integTest('deploy with notification ARN', withDefaultFixture(async (fixture) =>
   }
 }));
 
+integTest('deploy with notification ARN as prop', withDefaultFixture(async (fixture) => {
+  const topicName = `${fixture.stackNamePrefix}-test-topic-prop`;
+
+  const response = await fixture.aws.sns('createTopic', { Name: topicName });
+  const topicArn = response.TopicArn!;
+
+  try {
+    await fixture.cdkDeploy('notification-arn-prop');
+
+    // verify that the stack we deployed has our notification ARN
+    const describeResponse = await fixture.aws.cloudFormation('describeStacks', {
+      StackName: fixture.fullStackName('notification-arn-prop'),
+    });
+    expect(describeResponse.Stacks?.[0].NotificationARNs).toEqual([topicArn]);
+  } finally {
+    await fixture.aws.sns('deleteTopic', {
+      TopicArn: topicArn,
+    });
+  }
+}));
+
 // NOTE: this doesn't currently work with modern-style synthesis, as the bootstrap
 // role by default will not have permission to iam:PassRole the created role.
 integTest('deploy with role', withDefaultFixture(async (fixture) => {

packages/aws-cdk-lib/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts

@@ -55,6 +55,13 @@ export interface AwsCloudFormationStackProperties {
    */
   readonly tags?: { [id: string]: string };
 
+  /**
+   * SNS Notification ARNs that should receive CloudFormation Stack Events.
+   *
+   * @default - No notification arns
+   */
+  readonly notificationArns?: string[];
+
   /**
    * The name to use for the CloudFormation stack.
    * @default - name derived from artifact ID

packages/aws-cdk-lib/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -345,6 +345,12 @@
                         "type": "string"
                     }
                 },
+                "notificationArns": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
                 "stackName": {
                     "description": "The name to use for the CloudFormation stack. (Default - name derived from artifact ID)",
                     "type": "string"

packages/aws-cdk-lib/cloud-assembly-schema/schema/cloud-assembly.version.json

@@ -1 +1 @@
-{"version":"36.0.0"}
+{"version":"37.0.0"}

packages/aws-cdk-lib/core/README.md

@@ -1242,6 +1242,18 @@ const stack = new Stack(app, 'StackName', {
 });
 ```
 
+### Receiving CloudFormation Stack Events
+
+You can add one or more SNS Topic ARNs to any Stack:
+
+```ts
+const stack = new Stack(app, 'StackName', {
+  notificationArns: ['arn:aws:sns:us-east-1:23456789012:Topic'],
+});
+```
+
+Stack events will be sent to any SNS Topics in this list.
+
 ### CfnJson
 
 `CfnJson` allows you to postpone the resolution of a JSON blob from

packages/aws-cdk-lib/core/lib/stack-synthesizers/_shared.ts

@@ -48,6 +48,7 @@ export function addStackArtifactToAssembly(
     terminationProtection: stack.terminationProtection,
     tags: nonEmptyDict(stack.tags.tagValues()),
     validateOnSynth: session.validateOnSynth,
+    notificationArns: stack._notificationArns,
     ...stackProps,
     ...stackNameProperty,
   };

packages/aws-cdk-lib/core/lib/stack.ts

@@ -127,6 +127,13 @@ export interface StackProps {
    */
   readonly tags?: { [key: string]: string };
 
+  /**
+   * SNS Topic ARNs that will receive stack events.
+   *
+   * @default - no notfication arns.
+   */
+  readonly notificationArns?: string[];
+
   /**
    * Synthesis method to use while deploying this stack
    *
@@ -364,6 +371,13 @@ export class Stack extends Construct implements ITaggable {
    */
   public readonly _crossRegionReferences: boolean;
 
+  /**
+   * SNS Notification ARNs to receive stack events.
+   *
+   * @internal
+   */
+  public readonly _notificationArns: string[];
+
   /**
    * Logical ID generation strategy
    */
@@ -450,6 +464,7 @@ export class Stack extends Construct implements ITaggable {
       throw new Error(`Stack name must be <= 128 characters. Stack name: '${this._stackName}'`);
     }
     this.tags = new TagManager(TagType.KEY_VALUE, 'aws:cdk:stack', props.tags);
+    this._notificationArns = props.notificationArns ?? [];
 
     if (!VALID_STACK_NAME_REGEX.test(this.stackName)) {
       throw new Error(`Stack name must match the regular expression: ${VALID_STACK_NAME_REGEX.toString()}, got '${this.stackName}'`);

packages/aws-cdk-lib/core/test/stack.test.ts

@@ -2075,6 +2075,21 @@ describe('stack', () => {
     expect(asm.getStackArtifact(stack2.artifactId).tags).toEqual(expected);
   });
 
+  test('stack notification arns are reflected in the stack artifact properties', () => {
+    // GIVEN
+    const NOTIFICATION_ARNS = ['arn:aws:sns:bermuda-triangle-1337:123456789012:MyTopic'];
+    const app = new App({ stackTraces: false });
+    const stack1 = new Stack(app, 'stack1', {
+      notificationArns: NOTIFICATION_ARNS,
+    });
+
+    // THEN
+    const asm = app.synth();
+    const expected = { foo: 'bar' };
+
+    expect(asm.getStackArtifact(stack1.artifactId).notificationArns).toEqual(NOTIFICATION_ARNS);
+  });
+
   test('Termination Protection is reflected in Cloud Assembly artifact', () => {
     // if the root is an app, invoke "synth" to avoid double synthesis
     const app = new App();

packages/aws-cdk-lib/cx-api/lib/artifacts/cloudformation-artifact.ts

@@ -54,6 +54,11 @@ export class CloudFormationStackArtifact extends CloudArtifact {
    */
   public readonly tags: { [id: string]: string };
 
+  /**
+   * SNS Topics that will receive stack events.
+   */
+  public readonly notificationArns: string[];
+
   /**
    * The physical name of this stack.
    */
@@ -158,6 +163,7 @@ export class CloudFormationStackArtifact extends CloudArtifact {
     // We get the tags from 'properties' if available (cloud assembly format >= 6.0.0), otherwise
     // from the stack metadata
     this.tags = properties.tags ?? this.tagsFromMetadata();
+    this.notificationArns = properties.notificationArns ?? [];
     this.assumeRoleArn = properties.assumeRoleArn;
     this.assumeRoleExternalId = properties.assumeRoleExternalId;
     this.cloudFormationExecutionRoleArn = properties.cloudFormationExecutionRoleArn;

packages/aws-cdk-lib/cx-api/test/stack-artifact.test.ts

@@ -21,6 +21,24 @@ afterEach(() => {
   rimraf(builder.outdir);
 });
 
+test('read notification arns from artifact properties', () => {
+// GIVEN
+  const NOTIFICATION_ARNS = ['arn:aws:sns:bermuda-triangle-1337:123456789012:MyTopic'];
+  builder.addArtifact('Stack', {
+    ...stackBase,
+    properties: {
+      ...stackBase.properties,
+      notificationArns: NOTIFICATION_ARNS,
+    },
+  });
+
+  // WHEN
+  const assembly = builder.buildAssembly();
+
+  // THEN
+  expect(assembly.getStackByName('Stack').notificationArns).toEqual(NOTIFICATION_ARNS);
+});
+
 test('read tags from artifact properties', () => {
   // GIVEN
   builder.addArtifact('Stack', {

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

@@ -644,6 +644,12 @@ async function canSkipDeploy(
     return false;
   }
 
+  // Notification arns have changed
+  if (!arrayEquals(cloudFormationStack.notificationArns, deployStackOptions.notificationArns ?? [])) {
+    debug(`${deployName}: notification arns have changed`);
+    return false;
+  }
+
   // Termination protection has been updated
   if (!!deployStackOptions.stack.terminationProtection !== !!cloudFormationStack.terminationProtection) {
     debug(`${deployName}: termination protection has been updated`);
@@ -694,3 +700,7 @@ function suffixWithErrors(msg: string, errors?: string[]) {
     ? `${msg}: ${errors.join(', ')}`
     : msg;
 }
+
+function arrayEquals(a: any[], b: any[]): boolean {
+  return a.every(item => b.includes(item)) && b.every(item => a.includes(item));
+}

packages/aws-cdk/lib/api/util/cloudformation.ts

@@ -138,12 +138,21 @@ export class CloudFormationStack {
   /**
    * The stack's current tags
    *
-   * Empty list of the stack does not exist
+   * Empty list if the stack does not exist
    */
   public get tags(): CloudFormation.Tags {
     return this.stack?.Tags || [];
   }
 
+  /**
+   * SNS Topic ARNs that will receive stack events.
+   *
+   * Empty list if the stack does not exist
+   */
+  public get notificationArns(): CloudFormation.NotificationARNs {
+    return this.stack?.NotificationARNs ?? [];
+  }
+
   /**
    * Return the names of all current parameters to the stack
    *

packages/aws-cdk/lib/cdk-toolkit.ts

@@ -161,7 +161,6 @@ export class CdkToolkit {
         let changeSet = undefined;
 
         if (options.changeSet) {
-
           let stackExists = false;
           try {
             stackExists = await this.props.deployments.stackExists({
@@ -214,14 +213,6 @@ export class CdkToolkit {
       return this.watch(options);
     }
 
-    if (options.notificationArns) {
-      options.notificationArns.map( arn => {
-        if (!validateSnsTopicArn(arn)) {
-          throw new Error(`Notification arn ${arn} is not a valid arn for an SNS topic`);
-        }
-      });
-    }
-
     const startSynthTime = new Date().getTime();
     const stackCollection = await this.selectStacksForDeploy(options.selector, options.exclusively,
       options.cacheCloudAssembly, options.ignoreNoStacks);
@@ -318,7 +309,17 @@ export class CdkToolkit {
         }
       }
 
-      const stackIndex = stacks.indexOf(stack)+1;
+      let notificationArns: string[] = [];
+      notificationArns = notificationArns.concat(options.notificationArns ?? []);
+      notificationArns = notificationArns.concat(stack.notificationArns);
+
+      notificationArns.map(arn => {
+        if (!validateSnsTopicArn(arn)) {
+          throw new Error(`Notification arn ${arn} is not a valid arn for an SNS topic`);
+        }
+      });
+
+      const stackIndex = stacks.indexOf(stack) + 1;
       print('%s: deploying... [%s/%s]', chalk.bold(stack.displayName), stackIndex, stackCollection.stackCount);
       const startDeployTime = new Date().getTime();
 
@@ -335,7 +336,7 @@ export class CdkToolkit {
           roleArn: options.roleArn,
           toolkitStackName: options.toolkitStackName,
           reuseAssets: options.reuseAssets,
-          notificationArns: options.notificationArns,
+          notificationArns,
           tags,
           execute: options.execute,
           changeSetName: options.changeSetName,