(cloudformation-include): Support for referencing Serverless::Function .Version and .Alias attributes
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 83
Description
### Describe the feature
I'm proposing to add support to CfnInclude for templates which include references to Serverless referenceable properties (namely, `.Version` and `.Alias`) that are placeholders until the Transform is executed at deploy-time.
### Use Case
CfnInclude seems to work today with many templates that use the Serverless transform, but some edge cases exist that require workarounds. In this case, templates that need to reference a specific lambda version or alias effectively can't leverage `AutoPublishAlias` and require manual definition of versions, aliases, deployment groups, etc.
[This issue](https://github.com/aws/aws-cdk/issues/22071) (and subsequent [fix](https://github.com/aws/aws-cdk/pull/22126)) is a recent example of adding support for templates that leverage the Serverless transform (in that case, by supporting cyclic dependencies in templates).
### Proposed Solution
Going out on a limb a bit here, so I'm definitely soliciting input from folks more familiar with this module.
To maintain some consistency in the interface, we might consider adding an `allowDanglingReferences` props flag, following the [`allowCyclicalReferences` flag convention](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cloudformation-include/lib/cfn-include.ts#L68) (or a similar flag with a better name). Another option might be an allowlist of references that are expected to have no resolved target. I imagine there are other potential use-cases for this type of leniency outside of these two specific Serverless reference patterns, so I'd think it makes sense to be a bit more generic than is necessary for this issue alone.
In the parser itself, there are a few different situations that support somewhat similar behavior. One example being [leaving Resolvable objects alone](https://github.com/aws/aws-cdk/blob/24305376260407ea4101ffc6637470c1ecd97ec5/packages/%40aws-cdk/core/lib/helpers-internal/cfn-parse.ts#L486-L488). A potentially more-relevant example in the case of Ref parsing is the existing support for [special refs](https://github.com/aws/aws-cdk/blob/24305376260407ea4101ffc6637470c1ecd97ec5/packages/%40aws-cdk/core/lib/helpers-internal/cfn-parse.ts#L519-L522), which supports Refs of things like [AWS::Region and AWS::AccountId](https://github.com/aws/aws-cdk/blob/24305376260407ea4101ffc6637470c1ecd97ec5/packages/%40aws-cdk/core/lib/helpers-internal/cfn-parse.ts#L790-L805). Depending on the intended interface for `CfnInclude`, a flag (or allowlist) could be passed in `CfnParserOptions` to optionally allow for similar handling in cases where no ref target is found.
### Other Information
When `AutoPublishAlias` is set, the Serverless transform creates both a lambda Version and Alias resource at deployment time. These are [referenceable](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification-generated-resources-function.html#sam-specification-generated-resources-function-autopublishalias) via `.Version` and `.Alias` respectively. These references are replaced by the Serverless transform during deployment.
CfnInclude generally requires the targets of Ref expressions to exist within the template (e.g. [here](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cloudformation-include/lib/cfn-include.ts#L380), though the specific ICfnFinder implementation depends on the section of the template being parsed). Today, when trying to parse a template that includes one of these references, the result is
```
Error: Element used in Ref expression with logical ID: '.Version' not found
```
This specific issue has been raised [before](https://github.com/aws/aws-cdk/issues/19616), and was resolved with a different workaround using CfnApplication. This still seems like a reasonable bit of functionality to add, given both that this workaround doesn't result in the same effect as properly supported dangling references, as well as the existing support for some leniency in template parsing.
A small example template and code can be found in the [previous issue on this topic](https://github.com/aws/aws-cdk/issues/19616).
### Acknowledgements
- [X] I may be able to implement this feature request
- [ ] This feature might incur a breaking change
### CDK version used
2.43.1
### Environment details (OS name and version, etc.)
macOS Monterey v12.6
Contributor guide
Research direction
Start with packages/@aws-cdk/cloudformation-include/lib/cfn-include.ts, especially the allowCyclicalReferences convention and target lookup, then read the referenced handling in packages/@aws-cdk/core/lib/helpers-internal/cfn-parse.ts. Use the example from issue #19616 to trace .Version and .Alias references. Done means CfnInclude can parse these Serverless placeholders without the missing-target error while preserving existing reference validation.
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
- 35/100