feat: Add CloudFormation Language Extensions support (Fn::ForEach) by bnusunny · Pull Request #8637 · aws/aws-sam-cli

bnusunny · 2026-02-09T00:16:17Z

Description

This PR adds support for CloudFormation Language Extensions in SAM CLI, addressing GitHub issue #5647.

Features

Fn::ForEach - Iterate over collections to generate resources
Fn::Length - Get the length of an array
Fn::ToJsonString - Convert objects to JSON strings
Fn::FindInMap with DefaultValue - Map lookups with fallback values
Conditional DeletionPolicy/UpdateReplacePolicy - Use intrinsic functions like Fn::If in resource policies

Key Design Decisions

In-Memory Expansion Only - Templates are expanded in memory for SAM CLI operations, but the original unexpanded template is preserved for CloudFormation deployment
Dynamic Artifact Properties via Mappings - Fn::ForEach blocks with dynamic artifact properties (e.g., CodeUri: ./src/${Name}) are supported via a Mappings transformation
Locally Resolvable Collections Only - Fn::ForEach collections must be resolvable locally; cloud-dependent values (Fn::GetAtt, Fn::ImportValue) are not supported with clear error messages

Supported Commands

sam build - Builds all expanded functions, preserves original template
sam package - Preserves Fn::ForEach structure with S3 URIs
sam deploy - Uploads original template for CloudFormation to process
sam validate - Validates language extension syntax
sam local invoke - Invokes expanded functions by name
sam local start-api - Serves ForEach-generated API endpoints
sam local start-lambda - Serves all expanded functions

Example

Transform:
  - AWS::LanguageExtensions
  - AWS::Serverless-2016-10-31

Resources:
  Fn::ForEach::Functions:
    - Name
    - [Alpha, Beta, Gamma]
    - ${Name}Function:
        Type: AWS::Serverless::Function
        Properties:
          Handler: ${Name}.handler
          CodeUri: ./src
          Runtime: python3.9

Resolves #5647

Testing

Comprehensive unit tests for the language extensions engine
Integration tests for all supported commands
Test templates covering static/dynamic CodeUri, nested stacks, parameter collections

Checklist

Unit tests added
Integration tests added
Documentation in code comments
Error messages include actionable workarounds

bnusunny · 2026-02-09T01:07:11Z

Integration test: https://github.com/aws/aws-sam-cli/actions/runs/21808626015

Implement a local CloudFormation Language Extensions processor supporting: - Fn::ForEach loop expansion in Resources, Conditions, and Outputs - Fn::Length, Fn::ToJsonString intrinsic functions - Fn::FindInMap with DefaultValue support - Conditional DeletionPolicy/UpdateReplacePolicy - Nested ForEach depth validation (max 5 levels) - Partial resolution mode preserving unresolvable references Pipeline architecture: TemplateParsingProcessor -> ForEachProcessor -> IntrinsicResolverProcessor -> DeletionPolicyProcessor -> UpdateReplacePolicyProcessor Includes comprehensive unit tests and CloudFormation compatibility suite.

Wire the language extensions library into SAM CLI with two-phase architecture: - Phase 1: expand_language_extensions() -> LanguageExtensionResult - Phase 2: SamTranslatorWrapper.run_plugins() (SAM transform only) Key components: - expand_language_extensions() canonical entry point - SamTranslatorWrapper receives pre-expanded template (Phase 2 only) - SamLocalStackProvider.get_stacks() calls expand_language_extensions() - SamTemplateValidator calls expand_language_extensions() - DynamicArtifactProperty dataclass for Mappings transformation - Fn::ForEach guards in artifact_exporter, normalizer, cdk/utils

- _get_template_for_output() preserves Fn::ForEach in build output - _update_foreach_artifact_paths() generates Mappings for dynamic artifact properties with per-function build paths - Recursive nested Fn::ForEach support - ForEach-aware path resolution skips Docker image URIs Test templates: static CodeUri, dynamic CodeUri, parameter collections, nested stacks, nested ForEach, dynamic ImageUri, depth validation.

Package: - _export() calls expand_language_extensions() for Phase 1 - Preserves Fn::ForEach in packaged template with S3 URIs - Generates Mappings for dynamic artifact properties - _find_artifact_uri_for_resource() handles all export formats: string, {S3Bucket,S3Key}, {Bucket,Key}, {ImageUri} - Recursive nested Fn::ForEach support - Warning for parameter-based collections Deploy: - Uploads original unexpanded template to CloudFormation - Clear error for missing Mapping keys Integration tests for CodeUri, ContentUri, DefinitionUri, ImageUri, BodyS3Location across all packageable resource types.

- sam validate: valid ForEach, invalid syntax, cloud-dependent collections, dynamic CodeUri, nested depth validation (5 valid, 6 invalid) - sam local invoke: expanded function names from ForEach - sam local start-api: ForEach-generated API endpoints

Track CFNLanguageExtensions as a UsedFeature event when templates with AWS::LanguageExtensions transform are expanded. Emitted once per expansion in expand_language_extensions().

Remove redundant and AWS-dependent integration tests, keeping 9 essential tests across build, package, validate, local invoke, and start-api. Delete 34 orphaned testdata directories.

YAML parsing produces Python booleans for bare true/false values, but parameter overrides from --parameter-overrides are always strings. Fn::Equals was using Python == which returns False for 'true' == True. CloudFormation Fn::Equals performs string comparison, so convert both operands to their string representations before comparing. Booleans are lowercased to produce 'true'/'false' matching CFN serialization.

… only Language extension functions are only supported in these three sections per AWS::LanguageExtensions transform documentation. Previously the intrinsic resolver also processed Parameters, Mappings, Metadata, etc.

The name iter_regular_resources better conveys that ForEach blocks are skipped. Removes the backward-compatible alias.

Extract duplicated _to_boolean logic from condition_resolver.py and fn_if.py into IntrinsicFunctionResolver.to_boolean() static method. Replace os.path.isfile() + os.path.getmtime() two-step check with a single try/except around getmtime() to eliminate the race condition.

Remove 9 integration tests whose test data directories were removed in an earlier commit: validate/language-extensions/, buildcmd/language- extensions-dynamic-imageuri/, language-extensions-foreach/, and language-extensions-nested-foreach-{valid,invalid}/.

bnusunny · 2026-03-12T06:40:39Z

Integration test run: https://github.com/aws/aws-sam-cli/actions/runs/22987281510

seshubaws · 2026-03-13T20:18:51Z

tests/integration/testdata/buildcmd/language-extensions.yaml

+                  - Inventory
+
+
+  # Fn::ForEach::Topics:


Should this be uncommented?

seshubaws · 2026-03-13T20:29:38Z

...tegration/testdata/buildcmd/language-extensions-nested-foreach-dynamic-codeuri/template.yaml

+    - Env
+    - - dev
+      - prod
+    - Fn::ForEach::Services:


Why are we testing 2 nested stacks when I see we are also testing nested stacks that are 6 deep? I feel only the latter is necessary

seshubaws · 2026-03-13T20:33:15Z

tests/integration/testdata/buildcmd/language-extensions.yaml

+    Runtime: !Ref Runtime

 Resources:
-  Bucket:


We are we removing testing with lang extensions with different resources?

seshubaws · 2026-03-13T21:10:46Z

tests/unit/commands/_utils/test_template.py

+
+    def test_skips_non_sam_mappings(self):
+        """Mappings without the SAM prefix should not be modified."""
+        from samcli.commands._utils.template import _update_sam_mappings_relative_paths


move to top for all imports in the test methods

seshubaws · 2026-03-13T21:15:52Z

tests/unit/commands/_utils/test_template.py

+
+    def test_updates_relative_paths_in_sam_mappings(self):
+        """SAM-prefixed Mapping values that are relative paths should be adjusted."""
+        from samcli.commands._utils.template import _update_sam_mappings_relative_paths


move to top

seshubaws · 2026-03-13T21:19:32Z

tests/unit/commands/_utils/test_template.py

+
+        _update_sam_mappings_relative_paths({}, "/original", "/new")
+        _update_sam_mappings_relative_paths(None, "/original", "/new")
+


there is no assertion here?

seshubaws · 2026-03-13T21:47:39Z

tests/integration/testdata/package/language-extensions-foreach/template.yaml

+Resources:
+  # Test Fn::ForEach generating multiple Lambda functions with static CodeUri
+  # This generates AlphaFunction and BetaFunction, both using the same CodeUri
+  Fn::ForEach::Functions:


are we testing the other extensions like Fn::Length, Fn::FindInMap etc? Maybe I missed it

bnusunny requested a review from a team as a code owner February 9, 2026 00:16

github-actions bot added area/package sam package command area/deploy sam deploy command area/build sam build command pr/internal labels Feb 9, 2026

bnusunny force-pushed the feat-language-extension branch from 0be94d0 to 5d6cbf3 Compare February 9, 2026 00:33

bnusunny force-pushed the feat-language-extension branch 7 times, most recently from e68efa0 to 4ed8396 Compare February 13, 2026 02:55

roger-zhangg mentioned this pull request Feb 13, 2026

Fix #5647: Add support for Fn::ForEach intrinsic function #8298

Open

8 tasks

bnusunny force-pushed the feat-language-extension branch 15 times, most recently from 5324dad to 707baad Compare February 18, 2026 23:59

bnusunny force-pushed the feat-language-extension branch 4 times, most recently from 9baaa0d to d322ba2 Compare March 10, 2026 04:23

bnusunny requested a review from reedham-aws March 10, 2026 04:52

bnusunny force-pushed the feat-language-extension branch 4 times, most recently from 00160e1 to b2a44b9 Compare March 11, 2026 22:42

bnusunny added 12 commits March 12, 2026 04:52

feat: add telemetry tracking for CloudFormation Language Extensions

23c7496

Track CFNLanguageExtensions as a UsedFeature event when templates with AWS::LanguageExtensions transform are expanded. Emitted once per expansion in expand_language_extensions().

test: trim language extensions integration tests to essential cases

93bec52

Remove redundant and AWS-dependent integration tests, keeping 9 essential tests across build, package, validate, local invoke, and start-api. Delete 34 orphaned testdata directories.

refactor: rename iter_resources to iter_regular_resources

176c7d0

The name iter_regular_resources better conveys that ForEach blocks are skipped. Removes the backward-compatible alias.

bnusunny force-pushed the feat-language-extension branch from b2a44b9 to 6713896 Compare March 12, 2026 04:52

seshubaws reviewed Mar 13, 2026

View reviewed changes

tests/integration/testdata/buildcmd/language-extensions.yaml

- Inventory

# Fn::ForEach::Topics:

Copy link

Contributor

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be uncommented?

seshubaws reviewed Mar 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add CloudFormation Language Extensions support (Fn::ForEach)#8637

feat: Add CloudFormation Language Extensions support (Fn::ForEach)#8637
bnusunny wants to merge 12 commits intodevelopfrom
feat-language-extension

bnusunny commented Feb 9, 2026 •

edited

Loading

Uh oh!

bnusunny commented Feb 9, 2026

Uh oh!

bnusunny commented Mar 12, 2026

Uh oh!

seshubaws Mar 13, 2026

Uh oh!

seshubaws Mar 13, 2026

Uh oh!

seshubaws Mar 13, 2026

Uh oh!

seshubaws Mar 13, 2026 •

edited

Loading

Uh oh!

seshubaws Mar 13, 2026

Uh oh!

seshubaws Mar 13, 2026

Uh oh!

seshubaws Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		_update_sam_mappings_relative_paths({}, "/original", "/new")
		_update_sam_mappings_relative_paths(None, "/original", "/new")

Conversation

bnusunny commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Features

Key Design Decisions

Supported Commands

Example

Testing

Checklist

Uh oh!

bnusunny commented Feb 9, 2026

Uh oh!

bnusunny commented Mar 12, 2026

Uh oh!

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

seshubaws Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

seshubaws Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bnusunny commented Feb 9, 2026 •

edited

Loading

seshubaws Mar 13, 2026 •

edited

Loading