fix(aws-lambda): fail fast if a reserved environment variable is spec…

…ified (#22039)

I've found myself several times without thinking specifying `AWS_REGION` as an environment variable explicitly when writing a lambda function that needed to know the region, and only found it was problemattic and unnecessary at cloudformation deployment time.

This change adds a simple error to enable faster failures during development when a developer specifies a reserved environment variable name - it's purely a convenience change to help avoiding wasting time waiting for a deployment and rollback in an edge case where the developer is making a clear error.

This does not reference any existing issue.

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-lambda/lib/function.ts

@@ -898,6 +898,30 @@ export class Function extends FunctionBase {
    * @param options Environment variable options.
    */
   public addEnvironment(key: string, value: string, options?: EnvironmentOptions): this {
+    // Reserved environment variables will fail during cloudformation deploy if they're set.
+    // This check is just to allow CDK to fail faster when these are specified.
+    const reservedEnvironmentVariables = [
+      '_HANDLER',
+      '_X_AMZN_TRACE_ID',
+      'AWS_REGION',
+      'AWS_EXECUTION_ENV',
+      'AWS_LAMBDA_FUNCTION_NAME',
+      'AWS_LAMBDA_FUNCTION_MEMORY_SIZE',
+      'AWS_LAMBDA_FUNCTION_VERSION',
+      'AWS_LAMBDA_INITIALIZATION_TYPE',
+      'AWS_LAMBDA_LOG_GROUP_NAME',
+      'AWS_LAMBDA_LOG_STREAM_NAME',
+      'AWS_ACCESS_KEY',
+      'AWS_ACCESS_KEY_ID',
+      'AWS_SECRET_ACCESS_KEY',
+      'AWS_SESSION_TOKEN',
+      'AWS_LAMBDA_RUNTIME_API',
+      'LAMBDA_TASK_ROOT',
+      'LAMBDA_RUNTIME_DIR',
+    ];
+    if (reservedEnvironmentVariables.includes(key)) {
+      throw new Error(`${key} environment variable is reserved by the lambda runtime and can not be set manually. See https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html`);
+    }
     this.environment[key] = { value, ...options };
     return this;
   }

packages/@aws-cdk/aws-lambda/test/function.test.ts

@@ -3114,6 +3114,18 @@ test('FunctionVersionUpgrade adds new description to function', () => {
   });
 });
 
+test('function using a reserved environment variable', () => {
+  const stack = new cdk.Stack();
+  expect(() => new lambda.Function(stack, 'MyLambda', {
+    code: new lambda.InlineCode('foo'),
+    handler: 'index.handler',
+    runtime: lambda.Runtime.PYTHON_3_9,
+    environment: {
+      AWS_REGION: 'ap-southeast-2',
+    },
+  })).toThrow(/AWS_REGION environment variable is reserved/);
+});
+
 function newTestLambda(scope: constructs.Construct) {
   return new lambda.Function(scope, 'MyLambda', {
     code: new lambda.InlineCode('foo'),