feat(core): weak cross environment references by otaviomacedo · Pull Request #37800 · aws/aws-cdk

otaviomacedo · 2026-05-08T09:21:19Z

Reason for this change

With the introduction of the CloudFormation intrinsic Fn::GetStackOutput, we can provide users with the ability to create weak references between resources in different regions. The function also allows cross-account references, which are currently not supported by the CDK.

Description of changes

Introduce a context key @aws-cdk/core:crossStackReferenceStrength that lets users choose between strong references (producer cannot be deleted while consumers exist) and weak references (producer can be deleted independently). Users set the context key in cdk.json to one of three values:

"strong" (default): ExportWriter/ExportReader via SSM — producer cannot be deleted while consumers exist.
"weak": Fn::GetStackOutput — simpler, no extra infrastructure, but producer can be deleted independently.
"both": Transitional — producer keeps writing to SSM and exposes an Output; consumer reads via Fn::GetStackOutput. This allows removing the ExportReader without breaking anything.

Describe any new or updated permissions being added

For cross-account references, the producer stack gets an AWS::IAM::Role with a trust policy allowing the consumer's CloudFormation execution role to sts:AssumeRole, and an AWS::IAM::Policy granting cloudformation:DescribeStacks on the producer stack ARN.

Description of how you validated changes

New unit and integration tests
For the cross-account scenario, and the migration path (strong -> both -> weak), the change was tested manually.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

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

Introduce a context key `@aws-cdk/core:crossStackReferenceStrength` that lets users choose between strong references (producer cannot be deleted while consumers exist) and weak references (producer can be deleted independently). Users set the context key in `cdk.json` to one of three values: - `"strong"` (default): ExportWriter/ExportReader via SSM — producer cannot be deleted while consumers exist. - `"weak"`: `Fn::GetStackOutput` — simpler, no extra infrastructure, but producer can be deleted independently. - `"both"`: Transitional — producer keeps writing to SSM *and* exposes an Output; consumer reads via `Fn::GetStackOutput`. This allows removing the ExportReader without breaking anything.

github-actions · 2026-05-08T09:23:15Z

⚠️ This pull request description does not follow the correct template structure.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to follow the PR template and include a line like Closes #123 in the Issue section. If no existing issue matches your change, create one first.

github-actions · 2026-05-08T09:24:31Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	144 ran	144 passed

Test	Result
No test annotations available

View Security Guardian Results

github-actions · 2026-05-08T09:24:33Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	144 ran	144 passed

Test	Result
No test annotations available

View Security Guardian Results with resolved templates

rix0rrr · 2026-05-08T10:43:43Z

+    const stack = Stack.of(this);
+    const parameterName = `/${SSM_EXPORT_PATH_PREFIX}${exportName}`;
+
+    this._references.put(parameterName, stack.resolve(reference.toString()));


Make this logic shared with exportValue()?

rix0rrr · 2026-05-08T10:45:51Z


 export const STRING_LIST_REFERENCE_DELIMITER = '||';

+type CrossStackReferenceStrength = 'strong' | 'weak' | 'both';


Here's a trick so we can't accidentally make typoes:

const CROSS_STACK_REFERENCE_VALUES = ['strong', 'weak', 'both'] as const; type CrossStackReferenceStrength = (typeof CROSS_STACK_REFERENCE_VALUES)[number]; function crossStackReferenceStrength(scope: IConstruct): CrossStackReferenceStrength { // ... if (CROSS_STACK_REFERENCE_VALUES.includes(value)) { return value; } }

rix0rrr · 2026-05-08T10:46:54Z

-      `Stack "${consumer.node.path}" cannot reference ${renderReference(reference)} in stack "${producer.node.path}". ` +
-      'Cross stack references are only supported for stacks deployed to the same account or between nested stacks and their parent stack');
-  }
+    const strength = crossStackReferenceStrength(consumer);


This is worth documenting in the feature flag documentation: if this feature flag is flipped inside the construct tree, it's the scope of the consumer that counts, not the producer.

rix0rrr · 2026-05-08T10:50:03Z

+        'Strong cross-account references are not supported. Set the context key ' +
+        `"${cxapi.CROSS_STACK_REFERENCE_STRENGTH}" to "weak" or "both" to use Fn::GetStackOutput for cross-account references.`,


The mitigation seems to imply a difference in behavior that doens't actually exist. Also "not supported" is true but we can make it sound nicer 😉 .

How about something like:

Strong references requested, but cross-account references can only be weak. Acknowledge this warning or locally set the ${CROSS_STACK_REFERENCE_STRENGTH} flag to 'weak' to remove this message.

rix0rrr · 2026-05-08T10:50:30Z

+
+    if (strength === 'strong') {
+      Annotations.of(consumer).addWarningV2(
+        '@aws-cdk/core:crossAccountStrongRefsNotSupported',


Suggested change

'@aws-cdk/core:crossAccountStrongRefsNotSupported',

'@aws-cdk/core:crossAccountRefsAreAlwaysWeak',

rix0rrr · 2026-05-08T10:52:18Z

-      'Cross stack references are only supported for stacks deployed to the same environment or between nested stacks and their parent stack. ' +
-      'Set crossRegionReferences=true to enable cross region references');
+    // "weak" or "both" fallback — use Fn::GetStackOutput with cross-account role
+    if (consumer.synthesizer.cloudFormationExecutionRole == null) {


Not enjoying this limitation but I guess we can always remove it later.

rix0rrr · 2026-05-08T11:16:11Z

+
+      Migration path: set to \`"both"\` and deploy, then set to \`"weak"\` and deploy again.`,
+    introducedIn: { v2: 'V2NEXT' },
+    recommendedValue: 'weak',


One more thing: I think we definitely want weak as the recommended value eventually, but do we want to recommend this right now? Especially because in-env references will be far and away the most common, and each of them will cause a warning with this config.

aws-cdk-automation · 2026-05-08T11:32:49Z

➡️ PR build request submitted to test-main-pipeline ⬅️

A maintainer must now check the pipeline and add the pr-linter/cli-integ-tested label once the pipeline succeeds.

mergify · 2026-05-08T12:13:14Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2026-05-08T12:13:18Z

mergify · 2026-05-08T12:57:10Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2026-05-08T12:57:41Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

otaviomacedo requested a review from a team as a code owner May 8, 2026 09:21

otaviomacedo temporarily deployed to automation May 8, 2026 09:21 — with GitHub Actions Inactive

otaviomacedo had a problem deploying to automation May 8, 2026 09:21 — with GitHub Actions Failure

github-actions Bot added the p2 label May 8, 2026

otaviomacedo temporarily deployed to automation May 8, 2026 09:21 — with GitHub Actions Inactive

mergify Bot added the contribution/core This is a PR that came from AWS. label May 8, 2026

otaviomacedo requested a deployment to test-pipeline May 8, 2026 09:22 — with GitHub Actions Waiting

mergify Bot temporarily deployed to automation May 8, 2026 09:22 Inactive

mergify Bot temporarily deployed to test-pipeline May 8, 2026 09:23 Inactive

mergify Bot temporarily deployed to automation May 8, 2026 09:25 Inactive

Update tests

4281acc

otaviomacedo temporarily deployed to automation May 8, 2026 09:31 — with GitHub Actions Inactive

otaviomacedo temporarily deployed to test-pipeline May 8, 2026 09:32 — with GitHub Actions Inactive

otaviomacedo temporarily deployed to automation May 8, 2026 09:33 — with GitHub Actions Inactive

new test to ensure strong is the default value

6f84bc9

otaviomacedo temporarily deployed to automation May 8, 2026 09:40 — with GitHub Actions Inactive

aws-cdk-automation added the pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. label May 8, 2026

aws-cdk-automation temporarily deployed to automation May 8, 2026 09:40 — with GitHub Actions Inactive

otaviomacedo requested a deployment to test-pipeline May 8, 2026 09:41 — with GitHub Actions Waiting

aws-cdk-automation temporarily deployed to test-pipeline May 8, 2026 09:41 — with GitHub Actions Inactive

aws-cdk-automation temporarily deployed to automation May 8, 2026 09:49 — with GitHub Actions Inactive

eslint

fb72712

aws-cdk-automation temporarily deployed to automation May 8, 2026 10:43 — with GitHub Actions Inactive

rix0rrr reviewed May 8, 2026

View reviewed changes

aws-cdk-automation requested a deployment to test-pipeline May 8, 2026 10:44 — with GitHub Actions Waiting

rix0rrr reviewed May 8, 2026

View reviewed changes

Address comments

0418452

otaviomacedo temporarily deployed to automation May 8, 2026 11:30 — with GitHub Actions Inactive

otaviomacedo temporarily deployed to test-pipeline May 8, 2026 11:31 — with GitHub Actions Inactive

otaviomacedo temporarily deployed to automation May 8, 2026 11:32 — with GitHub Actions Inactive

rix0rrr approved these changes May 8, 2026

View reviewed changes

Merge branch 'main' into otaviom/gso-weak-strong-refs

90cadd0

mergify Bot temporarily deployed to automation May 8, 2026 12:13 Inactive

mergify Bot requested a deployment to test-pipeline May 8, 2026 12:14 Waiting

mergify Bot merged commit fe23dce into main May 8, 2026
22 of 24 checks passed

mergify Bot deleted the otaviom/gso-weak-strong-refs branch May 8, 2026 12:57

github-actions Bot locked as resolved and limited conversation to collaborators May 8, 2026

aws-cdk-automation removed the pr/needs-maintainer-review This PR needs a review from a Core Team Member label May 8, 2026

aws-cdk-automation temporarily deployed to automation May 8, 2026 12:58 — with GitHub Actions Inactive

aws-cdk-automation requested a deployment to test-pipeline May 8, 2026 12:59 — with GitHub Actions Waiting


		export const STRING_LIST_REFERENCE_DELIMITER = '\|\|';

		type CrossStackReferenceStrength = 'strong' \| 'weak' \| 'both';

		'Strong cross-account references are not supported. Set the context key ' +
		`"${cxapi.CROSS_STACK_REFERENCE_STRENGTH}" to "weak" or "both" to use Fn::GetStackOutput for cross-account references.`,

	'@aws-cdk/core:crossAccountStrongRefsNotSupported',
	'@aws-cdk/core:crossAccountRefsAreAlwaysWeak',

Conversation

otaviomacedo commented May 8, 2026

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

github-actions Bot commented May 8, 2026

Uh oh!

github-actions Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

aws-cdk-automation commented May 8, 2026

Uh oh!

mergify Bot commented May 8, 2026

Uh oh!

mergify Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

mergify Bot commented May 8, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented May 8, 2026 •

edited

Loading

github-actions Bot commented May 8, 2026 •

edited

Loading

mergify Bot commented May 8, 2026 •

edited

Loading