core: Provide visibility into the exports CDK implicitly creates
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 83
Description
### Describe the feature
The CDK should provide some way for users to identify automatically-created exports.
**Background**
CDK has a feature where, when one stack ("child") references a resource from another stack ("parent"), it'll automatically create an export in the parent stack.
This has a major catch, discussed at length [in the documentation](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#exportwbrvalueexportedvalue-options) and elsewhere on the internet, which is that it effectively creates a circular dependency between the two stacks. If you stop using the resource in the child stack, the cdk will try to remove the implicit export from the parent, deadlocking deployment until you figure out what was being implicitly exported and explicitly export it via `exportValue` or similar.
These implicit exports are a rather leaky abstraction, so it seems important to provide developers better visibility into the dependencies between stacks, especially implicitly-created ones.
### Use Case
- I or a member of my team is trying to remove a resource from a child stack and needs to figure out what attribute from the resource in the parent stack needs to be explicitly exported. Is it the ARN or the ID? Is it on the resource itself or a supporting resource like an IAM role or SG rule? I'd like the CDK or a supporting tool to be able to tell me.
- I, as a team lead, get sick of this happening and want to set a best-practice whereby all values that are consumed by other stacks should be explicitly exported. I'd like developers to be able to check manually for implicit imports and my CI pipeline or IDE to be able to find any. This is hard, because there's no way to distinguish an explicit export (using `exportValue`) from one that the CDK has implicitly created.
- Here's an example of a script that scans the CDK output and maps exports to imports:
https://gist.github.com/dleavitt/d18d25b4ecce40ba9b8f10bac1117c8c
It would be much more useful if it could distinguish explicit from implicit exports.
### Proposed Solution
The code that creates the implicit exports is here:
https://github.com/aws/aws-cdk/blob/febce9d8ae99e237d878d862877e4133f1adbce9/packages/aws-cdk-lib/core/lib/private/refs.ts#L195-L212
This code just calls `exportValue` with a single argument on the parent stack, indistinguishable from a similar call in application code. To be able to distinguish these implicit ones, I'd suggest either:
- Naming them such that they always have a certain format or prefix, e.g. `{StackName}:CDKAutoExportEtcEtc`.
- Adding a description, e.g. "Automatically created by CDK"
Either option would allow end-user tooling to distinguish between implicit and explicit exports. Both options seem backwards compatible and low-effort to implement.
Related, higher-effort, ideas:
- A CDK context flag to disable the automatic creation of these exports entirely.
- A CDK command that provides visibility into dependencies between stacks, listing exports and where they are consumed.
### Other Information
Editorial/general feedback: the code that controls this is relative simple, but it's buried in such a way that an end user can't really customize its behavior without forking the repo. This style of defensive programming seems to be pretty universal in the CDK codebase. I'd suggest that while minimizing API surface area like this is critical in the context of a large organization, it's not a good fit for open source.
There's no way to anticipate all the use-cases, so you should lean towards making things more hackable and thereby enable users to solve their problems in application code, rather than having to file tickets like this asking you to do it. ❤️
### Acknowledgements
- [X] I may be able to implement this feature request
- [ ] This feature might incur a breaking change
### CDK version used
2.154.1
### Environment details (OS name and version, etc.)
Mac OS 14.3
Contributor guide
Research direction
Start with packages/aws-cdk-lib/core/lib/private/refs.ts at the linked lines, where references cause the parent stack to call exportValue. Review the surrounding stack export behavior and the linked documentation, then determine how implicit exports can be distinguished from explicit ones. Done means end-user tooling can reliably identify automatically created exports without confusing them with application-defined exports.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- cloud, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100