From 7be47e1234a544cb1b37434d767914b708c9bb65 Mon Sep 17 00:00:00 2001 From: Mahdi Azarboon <21277296+azarboon@users.noreply.github.com> Date: Sat, 1 Mar 2025 08:16:17 +0800 Subject: [PATCH] docs(lambda): recommend a single source of truth for environment variables (#33587) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Issue # (if applicable) Closes #. This update improves the AWS Lambda component documentation in AWS CDK by recommending a single source of truth for environment variables. It addresses potential inconsistencies when defining environment variables separately in function code and infrastructure code, which can lead to mismatches during deployments. ### Reason for this change When updating a Lambda function in AWS CDK, CloudFormation applies configuration updates before code updates, which can temporarily cause environment variables to be removed or changed before the new function code is deployed. If the function executes during this period, it may fail due to missing or outdated environment variables. Defining environment variables in a single source of truth helps minimize inconsistencies and reduces the risk of deployment errors. ### Description of changes - Expanded documentation to emphasize defining environment variables centrally. - Clarified best practices for referencing environment variables in both the handler and infrastructure code. - Provided a recommendation to define environment variables in env.ts and reference them consistently. ### Describe any new or updated permissions being added ### Description of how you validated changes The updated recommendations were tested with a standard AWS CDK deployment to confirm that environment variables remain consistent across Lambda function executions. Ensured that the proposed approach aligns with AWS CDK’s best practices for maintainability and type safety. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- packages/aws-cdk-lib/aws-lambda/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/aws-cdk-lib/aws-lambda/README.md b/packages/aws-cdk-lib/aws-lambda/README.md index 04e659822d34e..963ba1eed80fb 100644 --- a/packages/aws-cdk-lib/aws-lambda/README.md +++ b/packages/aws-cdk-lib/aws-lambda/README.md @@ -24,6 +24,8 @@ related to a missing environment variable. To work around this, you can invoke your function against a version or alias by default, rather than the `$LATEST` version. +To further mitigate these issues, you can ensure consistency between your function code and infrastructure configuration by defining environment variables as a single source of truth in your CDK stack. You can define them in a separate `env.ts` file and reference them in both your handler and CDK configuration. This approach allows you to catch errors at compile time, benefit from improved IDE support, minimize the risk of mismatched configurations, and enhance maintainability. + ## Handler Code The `lambda.Code` class includes static convenience methods for various types of