Obter segredos e parâmetros para variáveis de ambiente do Elastic Beanstalk

O Elastic Beanstalk pode obter valores do AWS Secrets Manager e do AWS Systems Manager Parameter Store durante a inicialização da instância e atribuí-los a variáveis de ambiente para uso pela sua aplicação.

Os pontos a seguir resumem a configuração, a sincronização e o acesso para usar variáveis de ambiente como segredos:

Versões compatíveis da plataforma

As versões da plataforma lançadas em ou após 26 de março de 2025 oferecem suporte a segredos do AWS Secrets Manager e parâmetros do AWS Systems Manager Parameter Store configurados como variáveis de ambiente.

Preços

Cobranças padrão são aplicáveis ao uso do Secrets Manager e do Systems Manager Parameter Store. Para obter mais informações sobre preços, consulte os seguintes sites:

O Elastic Beanstalk não cobra pela referência da sua aplicação a segredos de ambiente por meio de variáveis de ambiente. No entanto, as tarifas padrão se aplicam às solicitações que o Elastic Beanstalk faz a esses serviços em seu nome.

Configurar segredos como variáveis de ambiente do Elastic Beanstalk

Você pode usar o console do Elastic Beanstalk, os arquivos de configuração em .ebextensions, a AWS CLI e o AWS SDK para configurar segredos e parâmetros como variáveis de ambiente.

Pré-requisitos

Antes de configurar suas variáveis de ambiente para referenciar segredos, é necessário concluir as seguintes etapas.

Utilizar o console

Você pode usar o console do Elastic Beanstalk para configurar segredos como variáveis de ambiente.

Configuração usando arquivos em .ebextensions

Você pode usar os arquivos de configuração do Elastic Beanstalk para configurar segredos como variáveis de ambiente. Use o aws:elasticbeanstalk:application:environmentsecrets namespace para definir propriedades do ambiente.

option_settings:
  aws:elasticbeanstalk:application:environmentsecrets:
    MY_SECRET: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret
    MY_PARAMETER: arn:aws:ssm:us-east-1:111122223333:parameter/myparam
        

option_settings:
  - namespace: aws:elasticbeanstalk:application:environmentsecrets
    option_name: MY_SECRET
    value: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret
  - namespace: aws:elasticbeanstalk:application:environmentsecrets
    option_name: MY_PARAMETER
    value: arn:aws:ssm:us-east-1:111122223333:parameter/myparam

Configuração usando a AWS CLI

É possível usar a AWS Command Line Interface (AWS CLI) para configurar segredos como variáveis de ambiente do Elastic Beanstalk. Esta seção fornece exemplos dos comandos create-environment e update-environment com o namespace aws:elasticbeanstalk:application:environmentsecrets. Quando o Elastic Beanstalk inicializa as instâncias do EC2 para os ambientes referenciados por esses comandos, ele inicializa as variáveis de ambiente com o segredo obtido e os valores dos parâmetros. Ele obtém esses valores dos respectivos ARNs do Secrets Manager e do Systems Manager Parameter Store.

Os dois exemplos a seguir usam o comando create-environment para adicionar um segredo e um parâmetro, configurados como variáveis de ambiente denominadas MY_SECRET e MY_PARAMETER.

aws elasticbeanstalk create-environment \
--region us-east-1 \
--application-name my-app \
--environment-name my-env \
--solution-stack-name "64bit Amazon Linux 2023 v6.5.0 running Node.js 20" \
--option-settings \
Namespace=aws:elasticbeanstalk:application:environmentsecrets,OptionName=MY_SECRET,Value=arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret \
Namespace=aws:elasticbeanstalk:application:environmentsecrets,OptionName=MY_PARAMETER,Value=arn:aws:ssm:us-east-1:111122223333:parameter/myparam 

Outra opção é usar um arquivo options.json para especificar as opções de namespace em vez de incluí-las inline.

aws elasticbeanstalk create-environment \
--region us-east-1 \
--application-name my-app \
--environment-name my-env \
--solution-stack-name "64bit Amazon Linux 2023 v6.5.0 running Node.js 20" \
--option-settings file://options.json

### example options.json ###
[
  {
    "Namespace": "aws:elasticbeanstalk:application:environmentsecrets",
    "OptionName": "MY_SECRET",
    "Value": "arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret"
  },
  {
    "Namespace": "aws:elasticbeanstalk:application:environmentsecrets",
    "OptionName": "MY_PARAMETER",
    "Value": "arn:aws:ssm:us-east-1:111122223333:parameter/myparam"
  }
]

O próximo exemplo configura variáveis de ambiente, denominadas MY_SECRET e MY_PARAMETER, para armazenar um segredo e um parâmetro para um ambiente existente. O comando update-environment transmite opções com a mesma sintaxe do comando create-environment, inline ou com um arquivo options.json. O exemplo a seguir demonstra o comando usando o mesmo arquivo options.json que também é usado no exemplo anterior.

aws elasticbeanstalk update-environment \
--region us-east-1 \
--application-name my-app \
--environment-name my-env \
--solution-stack-name "64bit Amazon Linux 2023 v6.5.0 running Node.js 20" \
--option-settings file://options.json

Configuração usando o AWS SDK

Você pode configurar segredos e parâmetros como variáveis de ambiente usando os AWS SDKs. Assim como os comandos update-environment e create-environment da AWS CLI mencionados na seção anterior, você pode usar as ações da API CreateEnvironment e UpdateEnvironment. Use o parâmetro de solicitação OptionSettings para especificar as opções do namespace aws:elasticbeanstalk:application:environmentsecrets.

Pratas recomendadas para sincronização de segredos com variáveis de ambiente do Elastic Beanstalk

Este tópico recomenda as práticas recomendadas para sua aplicação usar segredos de ambiente com o Secrets Manager ou o Systems Manager Parameter Store. Sua aplicação Elastic Beanstalk não receberá automaticamente os valores atualizados se os dados de armazenamento de segredos forem atualizados ou alternados. O Elastic Beanstalk só transfere segredos para variáveis de ambiente no momento do bootstrap da instância.

Atualizar suas variáveis de ambiente

Para acionar seu ambiente do Elastic Beanstalk para recuperar os valores mais recentes dos segredos dos seus armazenamentos de segredos, recomendamos que você execute a operação UpdateEnvironment ou RestartAppServer. Você pode executar essas operações usando o console do Elastic Beanstalk, a AWS CLI ou a API do Elastic Beanstalk. Para mais informações, consulte Exemplos da AWS CLI para o Elastic Beanstalk ou a Referência de APIs da AWS Elastic Beanstalk.

Gerenciar efeitos do ajuste de escala automático na sincronização de segredos

Se ocorrer um evento de aumento de escala horizontal ou uma troca de instância após as atualizações do armazenamento de segredos, a nova instância que for criada terá os valores de secredos mais recentes do Secrets Manager ou do Systems Manager Parameter Store. Esse evento pode ocorrer mesmo que nem todas as outras instâncias no ambiente tenham sido atualizadas para recuperar os novos segredos.

Um exemplo desse tipo de uso é a alternância de credenciais de banco de dados. Quando um evento de aumento de escala horizontal segue a alternância de credenciais, os segredos do ambiente referenciados pelas instâncias recém-inicializadas contêm as credenciais atualizadas do banco de dados. No entanto, os segredos do ambiente referenciados pelas instâncias existentes mantêm o valor antigo até serem atualizados pelas operações UpdateEnvironment ou RestartAppServer.

Valores multilinha nas variáveis de ambiente do Amazon Linux 2

Os valores multilinha são compostos por mais de uma linha e incluem um caractere de nova linha. Com exceção do Docker e das plataformas Docker baseadas em ECS, as plataformas que executam o Amazon Linux 2 não são compatíveis com valores multilinha para variáveis de ambiente.

As seguintes opções podem servir como soluções alternativas ou soluções para o problema de várias linhas: