From 6c5accd67495d2f1c851b0df2b6dfb9b9274a843 Mon Sep 17 00:00:00 2001
From: Evan K <113387406+evzzk@users.noreply.github.com>
Date: Fri, 17 Jan 2025 13:50:25 -1000
Subject: [PATCH] docs(lambda): add note on potential errors when updating
 lambda functions (#32838)

### Issue # (if applicable)

Closes #<issue number here>.

### Reason for this change

When you update multiple aspects of a Lambda function by modifying an
`aws-cdk-lib.aws-lambda` L2 construct and deploying in a single CDK
deployment, you may encounter a short period of time where errors occur
due to all aspects not being updated together.

### Description of changes

Add documentation in `aws-cdk-lib.aws-lambda` to explain this potential
situation.

### Describe any new or updated permissions being added

None

### Description of how you validated changes

None. Only updated README.md

### 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*

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Co-authored-by: Grace Luo <54298030+gracelu0@users.noreply.github.com>
---
 packages/aws-cdk-lib/aws-lambda/README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/packages/aws-cdk-lib/aws-lambda/README.md b/packages/aws-cdk-lib/aws-lambda/README.md
index 3dab77d5c021d..04e659822d34e 100644
--- a/packages/aws-cdk-lib/aws-lambda/README.md
+++ b/packages/aws-cdk-lib/aws-lambda/README.md
@@ -11,6 +11,19 @@ const fn = new lambda.Function(this, 'MyFunction', {
 });
 ```
 
+When deployed, this construct creates or updates an existing
+`AWS::Lambda::Function` resource. When updating, AWS CloudFormation calls the
+[UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html)
+and [UpdateFunctionCode](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionCode.html)
+Lambda APIs under the hood. Because these calls happen sequentially, and
+invocations can happen between these calls, your function may encounter errors
+in the time between the calls. For example, if you update an existing Lambda
+function by removing an environment variable and the code that references that
+environment variable in the same CDK deployment, you may see invocation errors
+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.
+
 ## Handler Code
 
 The `lambda.Code` class includes static convenience methods for various types of