Skip to content

Latest commit

 

History

History
308 lines (208 loc) · 17 KB

configuration-envvars.md

File metadata and controls

308 lines (208 loc) · 17 KB
Raw

Using AWS Lambda environment variables

You can use environment variables to adjust your function's behavior without updating code. An environment variable is a pair of strings that is stored in a function's version-specific configuration. The Lambda runtime makes environment variables available to your code and sets additional environment variables that contain information about the function and invocation request.

Note
To increase database security, we recommend that you use AWS Secrets Manager instead of environment variables to store database credentials. For more information, see Configuring database access for a Lambda function.

Environment variables are not evaluated prior to the function invocation. Any value you define is considered a literal string and not expanded. Perform the variable evaluation in your function code.

Topics

Configuring environment variables

You define environment variables on the unpublished version of your function. When you publish a version, the environment variables are locked for that version along with other version-specific configuration.

You create an environment variable for your function by defining a key and a value. Your function uses the name of the key to retrieve the value of environment variable.

To set environment variables in the Lambda console

  1. Open the Functions page on the Lambda console.

  2. Choose a function.

  3. Choose Configuration, then choose Environment variables.

  4. Under Environment variables, choose Edit.

  5. Choose Add environment variable.

  6. Enter a key and value.

Requirements

  • Keys start with a letter and are at least two characters.
  • Keys only contain letters, numbers, and the underscore character (_).
  • Keys aren't reserved by Lambda.
  • The total size of all environment variables doesn't exceed 4 KB.
  1. Choose Save.

Configuring environment variables with the API

To manage environment variables with the AWS CLI or AWS SDK, use the following API operations.

The following example sets two environment variables on a function named my-function.

aws lambda update-function-configuration --function-name my-function \
    --environment "Variables={BUCKET=my-bucket,KEY=file.txt}"

When you apply environment variables with the update-function-configuration command, the entire contents of the Variables structure is replaced. To retain existing environment variables when you add a new one, include all existing values in your request.

To get the current configuration, use the get-function-configuration command.

aws lambda get-function-configuration --function-name my-function

You should see the following output:

{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
    "Runtime": "nodejs12.x",
    "Role": "arn:aws:iam::123456789012:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "my-bucket",
            "KEY": "file.txt"
        }
    },
    "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
    ...
}

To ensure that the values don't change between when you read the configuration and when you update it, you can pass the revision ID from the output of get-function-configuration as a parameter to update-function-configuration.

To configure a function's encryption key, set the KMSKeyARN option.

aws lambda update-function-configuration --function-name my-function \
   --kms-key-arn arn:aws:kms:us-east-2:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

Example scenario for environment variables

You can use environment variables to customize function behavior in your test environment and production environment. For example, you can create two functions with the same code but different configurations. One function connects to a test database, and the other connects to a production database. In this situation, you use environment variables to tell the function the hostname and other connection details for the database.

The following example shows how to define the database host and database name as environment variables.

[]

If you want your test environment to generate more debug information than the production environment, you could set an environment variable to configure your test environment to use more verbose logging or more detailed tracing.

Retrieve environment variables

To retrieve environment variables in your function code, use the standard method for your programming language.

[ Node.js ]

let region = process.env.AWS_REGION

[ Python ]

import os
  region = os.environ['AWS_REGION']

Note
In some cases, you may need to use the following format:

region = os.environ.get('AWS_REGION')

[ Ruby ]

region = ENV["AWS_REGION"]

[ Java ]

String region = System.getenv("AWS_REGION");

[ Go ]

var region = os.Getenv("AWS_REGION")

[ C# ]

string region = Environment.GetEnvironmentVariable("AWS_REGION");

[ PowerShell ]

$region = $env:AWS_REGION

Lambda stores environment variables securely by encrypting them at rest. You can configure Lambda to use a different encryption key, encrypt environment variable values on the client side, or set environment variables in an AWS CloudFormation template with AWS Secrets Manager.

Defined runtime environment variables

Lambda runtimes set several environment variables during initialization. Most of the environment variables provide information about the function or runtime. The keys for these environment variables are reserved and cannot be set in your function configuration.

Reserved environment variables

  • _HANDLER – The handler location configured on the function.

  • _X_AMZN_TRACE_ID – The X-Ray tracing header.

  • AWS_REGION – The AWS Region where the Lambda function is executed.

  • AWS_EXECUTION_ENV – The runtime identifier, prefixed by AWS_Lambda_—for example, AWS_Lambda_java8.

  • AWS_LAMBDA_FUNCTION_NAME – The name of the function.

  • AWS_LAMBDA_FUNCTION_MEMORY_SIZE – The amount of memory available to the function in MB.

  • AWS_LAMBDA_FUNCTION_VERSION – The version of the function being executed.

    AWS_LAMBDA_INITIALIZATION_TYPE – The initialization type of the function, which is either on-demand or provisioned-concurrency. For information, see Configuring provisioned concurrency.

  • AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME – The name of the Amazon CloudWatch Logs group and stream for the function.

  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN – The access keys obtained from the function's execution role.

  • AWS_LAMBDA_RUNTIME_API – (Custom runtime) The host and port of the runtime API.

  • LAMBDA_TASK_ROOT – The path to your Lambda function code.

  • LAMBDA_RUNTIME_DIR – The path to runtime libraries.

  • TZ – The environment's time zone (UTC). The execution environment uses NTP to synchronize the system clock.

The following additional environment variables aren't reserved and can be extended in your function configuration.

Unreserved environment variables

  • LANG – The locale of the runtime (en_US.UTF-8).
  • PATH – The execution path (/usr/local/bin:/usr/bin/:/bin:/opt/bin).
  • LD_LIBRARY_PATH – The system library path (/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib).
  • NODE_PATH – (Node.js) The Node.js library path (/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules).
  • PYTHONPATH – (Python 2.7, 3.6, 3.8) The Python library path ($LAMBDA_RUNTIME_DIR).
  • GEM_PATH – (Ruby) The Ruby library path ($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0).
  • AWS_XRAY_CONTEXT_MISSING – For X-Ray tracing, Lambda sets this to LOG_ERROR to avoid throwing runtime errors from the X-Ray SDK.
  • AWS_XRAY_DAEMON_ADDRESS – For X-Ray tracing, the IP address and port of the X-Ray daemon.
  • AWS_LAMBDA_DOTNET_PREJIT – For the .NET 3.1 runtime, set this variable to enable or disable .NET 3.1 specific runtime optimizations. Values include always, never, and provisioned-concurrency. For information, see Configuring provisioned concurrency.

The sample values shown reflect the latest runtimes. The presence of specific variables or their values can vary on earlier runtimes.

Securing environment variables

For securing your environment variables, you can use server-side encryption to protect your data at rest and client-side encryption to protect your data in transit.

Note
To increase database security, we recommend that you use AWS Secrets Manager instead of environment variables to store database credentials. For more information, see Configuring database access for a Lambda function.

Security at rest
Lambda always provides server-side encryption at rest with an AWS KMS key. By default, Lambda uses an AWS managed key. If this default behavior suits your workflow, you don't need to set anything else up. Lambda creates the AWS managed key in your account and manages permissions to it for you. AWS doesn't charge you to use this key.

If you prefer, you can provide an AWS KMS customer managed key instead. You might do this to have control over rotation of the KMS key or to meet the requirements of your organization for managing KMS keys. When you use a customer managed key, only users in your account with access to the KMS key can view or manage environment variables on the function.

Customer managed keys incur standard AWS KMS charges. For more information, see AWS Key Management Service pricing, in the AWS KMS product pages.

Security in transit
For additional security, you can enable helpers for encryption in transit, which ensures that your environment variables are encrypted client-side for protection in transit.

To configure encryption for your environment variables

  1. Use the AWS Key Management Service (AWS KMS) to create any customer managed keys for Lambda to use for server-side and client-side encryption. For more information, see Creating keys in the AWS Key Management Service Developer Guide.

  2. Using the Lambda console, navigate to the Edit environment variables page.

    1. Open the Functions page on the Lambda console.

    2. Choose a function.

    3. Choose Configuration, then choose Environment variables from the left navigation bar.

    4. In the Environment variables section, choose Edit.

    5. Expand Encryption configuration.

  3. Optionally, enable console encryption helpers to use client-side encryption to protect your data in transit.

    1. Under Encryption in transit, choose Enable helpers for encryption in transit.

    2. For each environment variable that you want to enable console encryption helpers for, choose Encrypt next ot the environment variable.

    3. Under AWS KMS key to encrypt in transit, choose a customer managed key that you created at the beginning of this procedure.

    4. Choose Execution role policy and copy the policy. This policy grants permission to your function's execution role to decrypt the environment variables.

      Save this policy to use in the last step of this procedure.

    5. Add code to your function that decrypts the environment variables. Choose Decrypt secrets snippet to see an example.

  4. Optionally, specify your customer managed key for encryption at rest.

    1. Choose Use a customer master key.

    2. Choose a customer managed key that you created at the beginning of this procedure.

  5. Choose Save.

  6. Set up permissions.

    If you're using a customer managed key with server-side encryption, grant permissions to any AWS Identity and Access Management (IAM) users or roles that you want to be able to view or manange environment variables on the function. For more information, see Managing permissions to your server-side encryption KMS key.

    If you're enabling client-side encryption for security in transit, your function needs permission to call the kms:Decrypt API operation. Add the policy that you saved previously in this procedure to the function's execution role.

Managing permissions to your server-side encryption KMS key

No AWS KMS permissions are required for your user or the function's execution role to use the default encryption key. To use a customer managed key, you need permission to use the key. Lambda uses your permissions to create a grant on the key. This allows Lambda to use it for encryption.

  • kms:ListAliases – To view keys in the Lambda console.
  • kms:CreateGrant, kms:Encrypt – To configure a customer managed key on a function.
  • kms:Decrypt – To view and manage environment variables that are encrypted with a customer managed key.

You can get these permissions from your user account or from a key's resource-based permissions policy. ListAliases is provided by the managed policies for Lambda. Key policies grant the remaining permissions to users in the Key users group.

Users without Decrypt permissions can still manage functions, but they can't view environment variables or manage them in the Lambda console. To prevent a user from viewing environment variables, add a statement to the user's permissions that denies access to the default key, a customer managed key, or all keys.

Example IAM policy – Deny access by key ARN

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Deny",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-east-2:123456789012:key/3be10e2d-xmpl-4be4-bc9d-0405a71945cc"
        }
    ]
}

[]

For details on managing key permissions, see Using key policies in AWS KMS in the AWS Key Management Service Developer Guide.

Sample code and templates

Sample applications in this guide's GitHub repository demonstrate the use of environment variables in function code and AWS CloudFormation templates.

Sample applications

  • Blank function – Create a function and an Amazon SNS topic in the same template. Pass the name of the topic to the function in an environment variable. Read environment variables in code (multiple languages).
  • RDS MySQL – Create a VPC and an Amazon RDS DB instance in one template, with a password stored in Secrets Manager. In the application template, import database details from the VPC stack, read the password from Secrets Manager, and pass all connection configuration to the function in environment variables.