Como usar variáveis ​​de ambiente do Lambda

É possível usar variáveis de ambiente para ajustar o comportamento da função sem atualizar o código. Uma variável de ambiente é um par de strings armazenadas na configuração específica da versão de uma função. O runtime do Lambda disponibiliza variáveis de ambiente para o código e define variáveis de ambiente adicionais que contêm informações sobre a função e a solicitação de invocação.

nota

Para aumentar a segurança do banco de dados, recomendamos que você use o AWS Secrets Manager em vez de variáveis ​​de ambiente para armazenar as credenciais do banco de dados. Para ter mais informações, consulte O uso doAWS LambdaCom o Amazon RDS.

As variáveis ​​de ambiente não são avaliadas antes da invocação da função. Qualquer valor definido é considerado uma string literal e não expandido. Execute a avaliação da variável no seu código de função.

Configurar variáveis de ambiente (console)

Você define variáveis de ambiente na versão não publicada da sua função. Quando você publica uma versão, as variáveis de ambiente estão bloqueadas para essa versão junto com outras configurações específicas da versão.

Para criar uma variável de ambiente na sua função, defina uma chave e um valor. A função usa o nome da chave para recuperar o valor da variável de ambiente.

Para definir variáveis de ambiente no console do Lambda

1. Abra a página Funções do console do Lambda.

2. Escolha uma função.

3. Escolha Configuration (Configuração) e, em seguida, Environment variables (Variáveis de ambiente).

4. Em Environment variables (Variáveis de ambiente), selecione Edit (Editar).

5. Escolha Add environment variable (Adicionar variável de ambiente).

6. Insira um par de chave e valor.

   Requisitos

   • As chaves começam com uma letra e têm pelo menos dois caracteres.

   • As chaves e os valores contêm somente letras, números e o caractere de sublinhado (_).

   • As chaves não são reservadas pelo Lambda.

   • O tamanho total de todas as variáveis de ambiente não excede 4 KB.

7. Escolha Salvar.

Gerar uma lista de variáveis ​​de ambiente no editor de código do console

Você pode gerar uma lista de variáveis ​​de ambiente no editor de código do Lambda. Esta é uma maneira rápida de referenciar as variáveis ​​de ambiente enquanto você realiza a codificação.

1. Escolha a guia Código.

2. Escolha a guia Variáveis de ambiente.

3. Escolha Ferramentas, Mostrar variáveis de ambiente.

As variáveis ​​de ambiente permanecem criptografadas quando estão listadas no editor de código do console. Se você habilitou os auxiliares de criptografia para a criptografia em trânsito, essas configurações permanecerão inalteradas. Para ter mais informações, consulte Proteger variáveis de ambiente.

A lista de variáveis ​​de ambiente é somente leitura e está disponível somente no console do Lambda. Este arquivo não está incluso quando você realiza download do arquivo .zip da função e não é possível adicionar variáveis ​​de ambiente ao fazer upload deste arquivo.

Configurar variáveis de ambiente (API)

Para gerenciar variáveis de ambiente com a AWS CLI ou o AWS SDK, use as operações de API a seguir.

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Configurar variáveis de ambiente (AWS CLI)

O exemplo a seguir define duas variáveis de ambiente em uma função denominada my-function.

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

Quando você aplica variáveis de ambiente com o comando update-function-configuration, todo o conteúdo da estrutura Variables é substituído. Para manter variáveis de ambiente existentes ao adicionar uma nova, inclua todos os valores existentes em sua solicitação.

Para obter a configuração atual, use o comando get-function-configuration.

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

A seguinte saída deverá ser mostrada:

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

É possível transmitir o ID de revisão da saída de get-function-configuration como um parâmetro para update-function-configuration. Isso garante que os valores não sejam alterados entre quando você lê a configuração e quando a atualiza.

Para configurar a chave de criptografia de uma função, defina a opção KMSKeyARN.

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

Configurar variáveis de ambiente (AWS SAM)

Você pode usar o AWS Serverless Application Model para configurar as variáveis de ambiente da função. Atualize as propriedades Ambiente e Variáveis no arquivo template.yaml e execute o comando sam deploy.

exemplo template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An AWS Serverless Application Model template describing your function.
Resources:
  my-function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Description: ''
      MemorySize: 128
      Timeout: 120
      Handler: index.handler
      Runtime: nodejs18.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          BUCKET: my-bucket
          KEY: file.txt
      # Other function properties...

Exemplo de cenário para variáveis de ambiente

Você pode usar variáveis de ambiente para personalizar o comportamento da função no ambiente de teste e no ambiente de produção. Por exemplo, você pode criar duas funções com o mesmo código, mas configurações diferentes. Uma função se conecta a um banco de dados de teste e a outra se conecta a um banco de dados de produção. Nessa situação, você usa variáveis ​​de ambiente para transmitir o nome do host e outros detalhes de conexão do banco de dados para a função.

O exemplo a seguir mostra como definir o host do banco de dados e o nome do banco de dados como variáveis de ambiente.

Se quiser que o ambiente de teste gere mais informações de depuração do que o ambiente de produção, você poderá definir uma variável de ambiente para configurar o ambiente de teste para usar um registro em log mais detalhado ou um rastreamento mais detalhado.

Recupere variáveis de ambiente

Para recuperar variáveis de ambiente em seu código de função, use o método padrão para a sua linguagem de programação.

Node.js

let region = process.env.AWS_REGION

Python

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

nota

Em alguns casos, talvez seja necessário usar o seguinte formato:

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

O Lambda armazena as variáveis de ambiente de forma segura, criptografando-as em repouso. É possível configurar o Lambda para usar uma chave de criptografia diferente, criptografar valores de variáveis de ambiente no lado do cliente ou definir variáveis de ambiente em um modelo do AWS CloudFormation com o AWS Secrets Manager.

Variáveis de ambiente com runtime definido

Os runtimes do Lambda definem diversas variáveis de ambiente durante a inicialização. A maioria das variáveis de ambiente fornece informações sobre a função ou o runtime. As chaves para essas variáveis de ambiente são reservadas e não podem ser definidas na configuração de sua função.

Variáveis de ambiente reservadas

• _HANDLER: o local do handler configurado na função.

• _X_AMZN_TRACE_ID— OCabeçalho do X-Ray. Essa variável de ambiente muda a cada invocação.

  • Essa variável de ambiente não está definida para runtimes somente para sistema operacional (a família provided de runtime). Você pode definir _X_AMZN_TRACE_ID para runtimes personalizados usando o cabeçalho da resposta Lambda-Runtime-Trace-Id do Próxima invocação.

  • Nas versões 17 e posteriores do runtime do Java, essa variável de ambiente não é usada. Em vez disso, o Lambda armazena informações de rastreamento na propriedade com.amazonaws.xray.traceHeader do sistema.

• AWS_DEFAULT_REGION: a Região da AWS padrão onde a função do Lambda é executada.

• AWS_REGION: a Região da AWS onde a função do Lambda é executada. Se estiver definido, esse valor substituirá AWS_DEFAULT_REGION.

  • Para obter mais informações sobre como usar as variáveis de ambiente da Região da AWS com AWS SDKs, consulte Região da AWS no Guia de referência de SDKs e ferramentas da AWS.

• AWS_EXECUTION_ENV: o identificador de runtime, prefixado por AWS_Lambda_ (por exemplo, AWS_Lambda_java8). Essa variável de ambiente não está definida para runtimes somente para sistema operacional (a família provided de runtime).

• AWS_LAMBDA_FUNCTION_NAME: o nome da função.

• AWS_LAMBDA_FUNCTION_MEMORY_SIZE: a quantidade de memória disponível para a função em MB.

• AWS_LAMBDA_FUNCTION_VERSION: a versão da função que está sendo executada.

• AWS_LAMBDA_INITIALIZATION_TYPE: o tipo de inicialização da função, que é on-demand, provisioned-concurrency ou snap-start. Para obter informações, consulte Configurar a simultaneidade provisionada ou Melhorando o desempenho da startup com o Lambda SnapStart.

• AWS_LAMBDA_LOG_GROUP_NAME,AWS_LAMBDA_LOG_STREAM_NAME: o nome do grupo Amazon CloudWatch Logs e do fluxo do para a função. As variáveis de ambiente AWS_LAMBDA_LOG_GROUP_NAME e AWS_LAMBDA_LOG_STREAM_NAME não estão disponíveis nas funções do Lambda SnapStart.

• AWS_ACCESS_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN: as chaves de acesso obtidas da função de execução da função.

• AWS_LAMBDA_RUNTIME_API: (runtime personalizado) o host e a porta da API de runtime.

• LAMBDA_TASK_ROOT: o caminho para o código da função do Lambda.

• LAMBDA_RUNTIME_DIR: o caminho para bibliotecas de runtime.

As variáveis de ambiente adicionais a seguir não são reservadas e podem ser estendidas na configuração de sua função.

Variáveis de ambiente não reservadas

• LANG: a localidade do runtime (en_US.UTF-8).

• PATH: o caminho de execução (/usr/local/bin:/usr/bin/:/bin:/opt/bin).

• LD_LIBRARY_PATH: o caminho da biblioteca do sistema (/var/lang/lib:/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib).

• NODE_PATH: (Node.js) o caminho da biblioteca Node.js (/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules).

• PYTHONPATH: (Python 2.7, 3.6, 3.8) o caminho da biblioteca Python ($LAMBDA_RUNTIME_DIR).

• GEM_PATH: (Ruby) o caminho da biblioteca Ruby ($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0).

• AWS_XRAY_CONTEXT_MISSING: para o rastreamento do X-Ray, o Lambda define isso como LOG_ERROR para evitar a execução de erros de runtime no X-Ray SDK.

• AWS_XRAY_DAEMON_ADDRESS: para o rastreamento do X-Ray, o endereço IP e a porta do daemon do X-Ray.

• AWS_LAMBDA_DOTNET_PREJIT: para os runtimes do .NET 6 e .NET 7, defina essa variável para ativar ou desativar otimizações específicas de runtime do .NET. Os valores incluem always, never e provisioned-concurrency. Para ter mais informações, consulte Configurar a simultaneidade provisionada.

• TZ: o fuso horário do ambiente (UTC). O ambiente de execução usa o NTP para sincronizar o relógio do sistema.

Os valores de exemplo mostrados refletem os runtimes mais recentes. A presença de variáveis específicas ou seus valores pode variar nos runtimes anteriores.

Proteger variáveis de ambiente

Para proteger suas variáveis de ambiente, você pode usar a criptografia do lado do servidor para proteger seus dados em repouso e a criptografia do lado do cliente para proteger seus dados em trânsito.

nota

Para aumentar a segurança do banco de dados, recomendamos que você use o AWS Secrets Manager em vez de variáveis ​​de ambiente para armazenar as credenciais do banco de dados. Para ter mais informações, consulte O uso doAWS LambdaCom o Amazon RDS.

Segurança em repouso

O Lambda sempre fornece criptografia do lado do servidor em repouso com AWS KMS key. Por padrão, o Lambda usa um Chave gerenciada pela AWS. Se esse comportamento padrão for adequado ao fluxo de trabalho, você não precisará configurar mais nada. O Lambda cria o Chave gerenciada pela AWS em sua conta e gerencia permissões para você. AWS não cobra para usar esta chave.

Se você preferir, pode fornecer uma AWS KMS chave gerenciada pelo cliente. Você pode fazer isso para ter controle sobre a alternância da chave KMS ou para atender aos requisitos de sua organização para gerenciar chaves KMS. Quando você fornece uma chave gerenciada pelo cliente, somente os usuários em sua conta com acesso à chave KMS podem visualizar ou gerenciar variáveis de ambiente na função.

As chaves gerenciadas pelo cliente incorrem em cobranças do AWS KMS padrão. Para obter mais informações, consulte Preços do AWS Key Management Service.

Segurança em trânsito

Para segurança adicional, você pode habilitar auxiliares para criptografia em trânsito, o que garante que suas variáveis de ambiente sejam criptografadas no lado do cliente para proteção em trânsito.

Para configurar a criptografia para suas variáveis de ambiente

1. Usar a AWS Key Management Service (AWS KMS) para criar quaisquer chaves gerenciadas pelo cliente para o Lambda usar para criptografia do lado do cliente e do servidor. Para obter mais informações, consulte Criar chaves no AWS Key Management Service Guia do desenvolvedor.

2. Usando o console do Lambda, navegue até a página Editar variáveis de ambiente.

   1. Abra a página Funções do console do Lambda.

   2. Escolha uma função.

   3. Selecione Configuração e, depois, escolha Variáveis de ambiente na barra de navegação à esquerda.

   4. Em Variáveis de ambiente, selecione Editar.

   5. Expanda Encryption configuration (Configuração de criptografia).

3. (Opcional) Habilite os auxiliares de criptografia do console para usar a criptografia do lado do cliente com a finalidade de proteger os dados em trânsito.

   1. Em Criptografia em trânsito, escolha Habilitar auxiliares para criptografia em trânsito.

   2. Para cada variável de ambiente na qual deseja habilitar os auxiliares de criptografia do console, escolha Encrypt (Criptografar) ao lado da variável de ambiente.

   3. Em AWS KMS key para criptografar em trânsito, escolha uma chave gerenciada pelo cliente criada no início deste procedimento.

   4. Selecione Política da função de execução e copie a política. Essa política concede permissão à função de execução de sua função para descriptografar variáveis de ambiente.

      Salve essa política para usar na última etapa deste procedimento.

   5. Adicione à sua função o código que descriptografa as variáveis de ambiente. Para ver um exemplo, escolha Snippet de descriptografia de segredos.

4. (Opcional) Especifique a chave gerenciada pelo cliente para a criptografia em repouso.

   1. Escolha Uso de chave primária do cliente.

   2. Escolha uma chave gerenciada pelo cliente que você criou no início deste procedimento.

5. Escolha Salvar.

6. Configurar permissões

   Se você estiver usando uma chave gerenciada pelo cliente com criptografia do lado do servidor, conceda permissões a todos os usuários ou perfis que deseja visualizar ou gerenciar variáveis ​​de ambiente na função. Para ter mais informações, consulte Gerenciar permissões para a chave KMS de criptografia do lado do servidor.

   Se você estiver habilitando a criptografia do lado do cliente para segurança em trânsito, sua função precisará de permissão para chamar o método operação da API kms:Decrypt. Adicione a política que você salvou anteriormente à Função de execução neste procedimento.

Gerenciar permissões para a chave KMS de criptografia do lado do servidor

Para usar a chave de criptografia padrão, não é necessária nenhuma permissão do AWS KMS para o usuário ou para a função de execução da função. Para usar uma chave gerenciada pelo cliente, é necessário permissão para usar a chave. O Lambda usa essas permissões para criar uma concessão na chave. Isso permite que o Lambda use-a para criptografia.

• kms:ListAliases: para visualizar as teclas no console do Lambda.

• kms:CreateGrant, kms:Encrypt – para configurar uma chave gerenciada pelo cliente em uma função.

• kms:Decrypt – para visualizar e gerenciar variáveis de ambiente criptografadas com uma chave gerenciada pelo cliente.

É possível obter essas permissões em sua Conta da AWS ou na política de permissões baseada em recursos de uma chave. ListAliases é fornecido pelas políticas gerenciadas para o Lambda. As políticas de chave concedem as permissões restantes aos usuários no grupo Usuários de chaves.

Os usuários sem permissões Decrypt ainda poderão gerenciar funções, mas não poderão visualizar variáveis de ambiente nem gerenciá-las no console do Lambda. Para impedir que um usuário visualize variáveis de ambiente, adicione uma declaração às permissões do usuário que negue o acesso à chave padrão, a uma chave gerenciada pelo cliente ou a todas as chaves.

exemplo Política do IAM: negar acesso pelo ARN da chave

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

Para obter detalhes sobre como gerenciar permissões de chave, consulte Key policies in AWS KMS no Guia do desenvolvedor do AWS Key Management Service.

Modelos e código de exemplo

As aplicações de exemplo no repositório do GitHub deste guia demonstram a utilização de variáveis de ambiente em modelos de código de função e de AWS CloudFormation.

Aplicações de exemplo

• Função em branco: crie uma função básica que mostre o uso de registro em log, variáveis de ambiente, rastreamento do AWS X-Ray, camadas, testes de unidade e o AWS SDK.

• RDS MySQL: crie uma VPC e uma instância de banco de dados do Amazon Relational Database Service (Amazon RDS) em um modelo, com uma senha armazenada no Secrets Manager. No modelo de aplicação, importe detalhes do banco de dados da pilha da VPC, leia a senha do Secrets Manager e passe toda a configuração da conexão para a função em variáveis de ambiente.