docs(lambda): add note on potential errors when updating lambda funct…

…ions (#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 <[email protected]>

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