fix: "duplicate Export names" error deploying nested stacks with Fn::Join exports (#1307)

CDK CLI v2.1116.0 added `IncludeNestedStacks: true` to the deploy
changeset creation path (PR #1292). This tells CloudFormation to
validate all nested stack templates together when creating a changeset.

However, CloudFormation cannot resolve intrinsic functions at changeset
validation time. When multiple nested stacks use `Fn::Join` (or similar
intrinsics) to build export names with runtime references,
CloudFormation collapses all of them to the same placeholder
`{{IntrinsicFunction://Fn::Join}}` and reports a false "duplicate Export
names" error. This affects patterns like the Amplify GraphQL API
construct which uses `Fn::Join` with an API ID to generate unique export
names across nested stacks.

This PR removes `IncludeNestedStacks` from the deploy changeset path,
reverting to the pre-v2.1116.0 behavior. The diff changeset path (`cdk
diff --method=change-set`) retains `IncludeNestedStacks` since
`--method=auto` (the default) already falls back to template-based diff
on error, and changeset diff didn't work for any nested stacks in
previous versions so the current behavior is strictly an improvement.

Internal reference D423570178

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

---------

Co-authored-by: 9pace <paceben@amazon.com>

Author: mrgrain

packages/@aws-cdk-testing/cli-integ/resources/cdk-apps/nested-stack-with-fn-join-export/app.js

@@ -0,0 +1,46 @@
+const cdk = require('aws-cdk-lib');
+const { aws_cloudformation: cfn, aws_sns: sns, aws_ssm: ssm } = cdk;
+
+/**
+ * Reproduces https://t.corp.amazon.com/D423570178
+ *
+ * When IncludeNestedStacks is true, CloudFormation validates all nested stacks
+ * together. Export names using Fn::Join with a runtime reference get collapsed
+ * to the placeholder {{IntrinsicFunction://Fn::Join}}, causing a false
+ * "duplicate Export names" error when 2+ such exports exist across nested stacks.
+ */
+
+class NestedStackWithFnJoinExports extends cfn.NestedStack {
+  constructor(scope, id, props) {
+    super(scope, id, props);
+    const topic = new sns.Topic(this, 'Topic');
+    new cdk.CfnOutput(this, 'ExportArn', {
+      value: topic.topicArn,
+      exportName: cdk.Fn.join(':', [props.runtimeRef, 'GetAtt', id, 'Arn']),
+    });
+    new cdk.CfnOutput(this, 'ExportName', {
+      value: topic.topicName,
+      exportName: cdk.Fn.join(':', [props.runtimeRef, 'GetAtt', id, 'Name']),
+    });
+  }
+}
+
+class NestedStacksFnJoinExportStack extends cdk.Stack {
+  constructor(scope, id, props) {
+    super(scope, id, props);
+    // SSM parameter name is a runtime reference (not known at validation time)
+    const param = new ssm.StringParameter(this, 'Param', { stringValue: 'value' });
+    new NestedStackWithFnJoinExports(this, 'Nested1', { runtimeRef: param.parameterName });
+    new NestedStackWithFnJoinExports(this, 'Nested2', { runtimeRef: param.parameterName });
+  }
+}
+
+const app = new cdk.App();
+
+const stackPrefix = process.env.STACK_NAME_PREFIX;
+if (!stackPrefix) {
+  throw new Error('the STACK_NAME_PREFIX environment variable is required');
+}
+
+new NestedStacksFnJoinExportStack(app, `${stackPrefix}-nested-stacks-fn-join-export`);
+app.synth();

packages/@aws-cdk-testing/cli-integ/resources/cdk-apps/nested-stack-with-fn-join-export/cdk.json

@@ -0,0 +1,7 @@
+{
+  "app": "node app.js",
+  "versionReporting": false,
+  "context": {
+    "aws-cdk:enableDiffNoFail": "true"
+  }
+}

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/deploy/cdk-deploy-nested-stacks-with-fn-join-export.integtest.ts

@@ -0,0 +1,11 @@
+import { integTest, withSpecificFixture } from '../../../lib';
+
+integTest(
+  'deploy nested stacks with Fn::Join export names',
+  withSpecificFixture('nested-stack-with-fn-join-export', async (fixture) => {
+    // This should succeed. With IncludeNestedStacks:true, CloudFormation
+    // incorrectly reports duplicate export names when multiple nested stacks
+    // use Fn::Join with the same runtime reference to build export names.
+    await fixture.cdkDeploy('nested-stacks-fn-join-export', { captureStderr: false });
+  }),
+);

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/deploy/cdk-deploy-skips-unnecessary-updates-for-nested-stacks.integtest.ts

@@ -4,9 +4,9 @@ import { integTest, withDefaultFixture } from '../../../lib';
 integTest(
   'deploy skips unnecessary updates for nested stacks',
   withDefaultFixture(async (fixture) => {
-    // Deploy a stack with nested stacks. With IncludeNestedStacks, CloudFormation
-    // can accurately detect whether nested stacks have actual changes, rather than
-    // always reporting them as needing an update.
+    // we are using a stack with a nested stack because CFN will always attempt to
+    // update a nested stack, which will allow us to verify that updates are actually
+    // skipped unless --force is specified.
     const stackArn = await fixture.cdkDeploy('with-nested-stack', { captureStderr: false });
     const changeSet1 = await getLatestChangeSet();
 
@@ -15,15 +15,10 @@ integTest(
     const changeSet2 = await getLatestChangeSet();
     expect(changeSet2.ChangeSetId).toEqual(changeSet1.ChangeSetId);
 
-    // Deploy the stack again with --force. CloudFormation creates a changeset but
-    // accurately reports no changes (including in nested stacks), so the changeset
-    // is not executed and the stack's ChangeSetId remains the same.
-    const forceOutput = await fixture.cdk(
-      fixture.cdkDeployCommandLine('with-nested-stack', { options: ['--force'] }),
-    );
-    expect(forceOutput).toContain('CloudFormation reported that the deployment would not make any changes');
+    // Deploy the stack again with --force, now we should create a changeset
+    await fixture.cdkDeploy('with-nested-stack', { options: ['--force'] });
     const changeSet3 = await getLatestChangeSet();
-    expect(changeSet3.ChangeSetId).toEqual(changeSet2.ChangeSetId);
+    expect(changeSet3.ChangeSetId).not.toEqual(changeSet2.ChangeSetId);
 
     // Deploy the stack again with tags, expected to create a new changeset
     // even though the resources didn't change.

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

@@ -31,7 +31,7 @@ import { DeploymentError, DeploymentErrorCodes, ToolkitError } from '../../toolk
 import { formatErrorMessage } from '../../util';
 import type { SDK, SdkProvider, ICloudFormationClient } from '../aws-auth/private';
 import type { TemplateBodyParameter } from '../cloudformation';
-import { makeBodyParameter, CfnEvaluationException, CloudFormationStack, templateContainsNestedStacks } from '../cloudformation';
+import { makeBodyParameter, CfnEvaluationException, CloudFormationStack } from '../cloudformation';
 import type { EnvironmentResources, StringWithoutPlaceholders } from '../environment';
 import { EnvironmentResourcesRegistry } from '../environment';
 import { HotswapPropertyOverrides, ICON, createHotswapPropertyOverrides } from '../hotswap/common';
@@ -470,7 +470,6 @@ class FullCloudFormationDeployment {
       Description: `CDK Changeset for execution ${this.uuid}`,
       ClientToken: `create${this.uuid}`,
       ImportExistingResources: importExistingResources,
-      IncludeNestedStacks: templateContainsNestedStacks(this.stackArtifact.template),
       DeploymentMode: revertDrift ? 'REVERT_DRIFT' : undefined,
       ...this.commonPrepareOptions(),
     });

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

@@ -48,6 +48,20 @@ const FAKE_STACK = testStack({
   stackName: 'withouterrors',
 });
 
+const FAKE_STACK_WITH_NESTED_STACK = testStack({
+  stackName: 'withnestedstack',
+  template: {
+    Resources: {
+      NestedStack: {
+        Type: 'AWS::CloudFormation::Stack',
+        Properties: {
+          TemplateURL: 'https://example.com/template.json',
+        },
+      },
+    },
+  },
+});
+
 const FAKE_STACK_WITH_PARAMETERS = testStack({
   stackName: 'withparameters',
   template: {
@@ -1316,3 +1330,17 @@ function givenChangeSetContainsReplacement(replacement: boolean) {
     ] : [],
   });
 }
+
+test('does not pass IncludeNestedStacks even for stacks with nested stacks', async () => {
+  // Regression test: IncludeNestedStacks causes CloudFormation to report false
+  // "duplicate Export names" errors when nested stacks use intrinsic functions
+  // (like Fn::Join) in export names.
+  await testDeployStack({
+    ...standardDeployStackArguments(),
+    stack: FAKE_STACK_WITH_NESTED_STACK,
+  });
+
+  const calls = mockCloudFormationClient.commandCalls(CreateChangeSetCommand);
+  expect(calls.length).toBeGreaterThan(0);
+  expect(calls[0].args[0].input).not.toHaveProperty('IncludeNestedStacks');
+});