AWS serverless-application-model documentation change
Summary
Added documentation for enabling AWS SAM language extensions via CLI flags, samconfig.toml, or environment variables; clarified opt-in requirements for local processing; added telemetry section for usage tracking.
Security assessment
The changes focus on operational aspects of language extensions (opt-in mechanisms, command usage, telemetry) without addressing vulnerabilities, security controls, or security features. No security advisories, vulnerability fixes, or security enhancements are mentioned.
Diff
diff --git a/serverless-application-model/latest/developerguide/sam-specification-language-extensions.md b/serverless-application-model/latest/developerguide/sam-specification-language-extensions.md index 4bdb5d3c8..a701f9c18 100644 --- a//serverless-application-model/latest/developerguide/sam-specification-language-extensions.md +++ b//serverless-application-model/latest/developerguide/sam-specification-language-extensions.md @@ -7 +7 @@ -Fn::ForEachSupported intrinsic functionsValidation errorsLimitations +Enabling language extensionsFn::ForEachSupported intrinsic functionsValidation errorsLimitationsTelemetry @@ -13 +13 @@ The AWS SAM CLI supports templates that use the `AWS::LanguageExtensions` transf -When the AWS SAM CLI detects `AWS::LanguageExtensions` in a template's `Transform` section, it expands language extension constructs locally before running AWS SAM transforms. This enables `sam build`, `sam package`, `sam deploy`, `sam sync`, `sam validate`, `sam local invoke`, and `sam local start-api` to work with templates that use these constructs. +To use language extensions in a AWS SAM template, list `AWS::LanguageExtensions` in the `Transform` section _before_ `AWS::Serverless-2016-10-31`: @@ -15 +15,11 @@ When the AWS SAM CLI detects `AWS::LanguageExtensions` in a template's `Transfor -The expansion happens in two phases: + + Transform: + - AWS::LanguageExtensions + - AWS::Serverless-2016-10-31 + + +When the AWS SAM CLI detects `AWS::LanguageExtensions` in a template's `Transform` section _and_ you have opted in to local processing, it expands language extension constructs locally before running AWS SAM transforms. This enables `sam build`, `sam package`, `sam deploy`, `sam sync`, `sam validate`, `sam local invoke`, `sam local start-api`, and `sam local start-lambda` to work with templates that use these constructs. + +Local processing is off by default. When off, the AWS SAM CLI passes the template through unchanged and CloudFormation processes the `AWS::LanguageExtensions` transform server-side at deploy time. For activation methods, see Enabling language extensions. + +The expansion happens in two phases when enabled: @@ -25,0 +36,58 @@ The original template (with `Fn::ForEach` intact) is preserved for CloudFormatio +## Enabling language extensions + +Local processing of `AWS::LanguageExtensions` is opt-in per command. There are three equivalent activation methods, listed in priority order: + + 1. **CLI flag** — pass `--language-extensions` on a single invocation: + + sam build --language-extensions + sam package --language-extensions ... + sam deploy --language-extensions ... + + +`--no-language-extensions` explicitly disables, overriding both `samconfig.toml` and the environment variable described below. + + 2. **`samconfig.toml`** — persist the choice per project: + + [default.build.parameters] + language_extensions = true + + [default.package.parameters] + language_extensions = true + + [default.deploy.parameters] + language_extensions = true + + [default.sync.parameters] + language_extensions = true + + [default.local_invoke.parameters] + language_extensions = true + + [default.local_start_api.parameters] + language_extensions = true + + [default.local_start_lambda.parameters] + language_extensions = true + + [default.validate.parameters] + language_extensions = true + + +A `samconfig.toml` entry is loaded as a default for the command, so it takes effect as if the flag were passed — and therefore wins over the environment variable. + + 3. **Environment variable** — set `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` to enable for the current shell: + + export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 + sam build + sam local invoke MyFunction + + +Truthy values (case-insensitive) are `1`, `true`, and `yes`. Anything else, including the empty string, is treated as off. The environment variable is consulted only when neither the CLI flag nor `samconfig.toml` sets a value. + + + + +###### Important + +Each command needs its own activation. Passing `--language-extensions` to `sam build` does not propagate to a later `sam local invoke` — local processing is decided per command invocation. Use the environment variable or a `samconfig.toml` entry to enable across commands without repeating the flag. + @@ -172 +240 @@ Because the `SAM*` Mappings are baked in at package time, you must re-package wh - sam package --parameter-overrides ServiceNames="Users,Orders,Products" + sam package --language-extensions --parameter-overrides ServiceNames="Users,Orders,Products" @@ -175 +243 @@ Because the `SAM*` Mappings are baked in at package time, you must re-package wh - sam deploy --parameter-overrides ServiceNames="Users,Orders,Products" + sam deploy --language-extensions --parameter-overrides ServiceNames="Users,Orders,Products" @@ -317,0 +386,4 @@ The `!Ref` in the collection points at a parameter that is not declared in the t +## Telemetry + +The AWS SAM CLI emits a `CFNLanguageExtensions` telemetry event when a command is invoked with `--language-extensions` (or its environment-variable equivalent) _and_ the template declares the `AWS::LanguageExtensions` transform. The event fires once per invocation and no template content is transmitted. When local processing is off (the default), no event fires. +