Ferramentas de script de plataforma - AWS Elastic Beanstalk
get-configpkg-repodownload-source-bundle (Somente Amazon Linux AMI)

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Ferramentas de script de plataforma

Este tópico descreve as ferramentas que AWS Elastic Beanstalk fornecem para ambientes que usam plataformas Amazon Linux. As ferramentas estão localizadas nas instâncias do Amazon EC2 dos ambientes do Elastic Beanstalk.

get-config

Use a ferramenta get-config para recuperar valores de variáveis de ambiente e outras informações da plataforma e da instância. A ferramenta está disponível em /opt/elasticbeanstalk/bin/get-config.

comandos get-config

Cada comando da ferramenta get-config retorna um tipo específico de informação. Use a sintaxe a seguir para executar os comandos de qualquer uma das ferramentas.

$ /opt/elasticbeanstalk/bin/get-config command [ options ]

O exemplo a seguir executa o comando environment:

$ /opt/elasticbeanstalk/bin/get-config environment -k PORT

Dependendo do comando e das opções que você escolher, a ferramenta retorna um objeto (JSON ou YAML) com pares de chave-valor ou um único valor.

É possível testar get-config usando SSH para se conectar a uma instância do EC2 no ambiente do Elastic Beanstalk.

nota

Quando você executa get-config para teste, alguns comandos podem exigir privilégios de usuário raiz para acessar as informações subjacentes. Se você receber um erro de permissão de acesso, execute o comando novamente em sudo.

Você não precisa adicionar sudo ao usar a ferramenta nos scripts implantados no ambiente. O Elastic Beanstalk executa todos os seus scripts como o usuário raiz.

As seções a seguir descrevem os comandos da ferramenta.

O comando get-config optionsettings retorna um objeto listando as opções de configuração definidas no ambiente e usadas pela plataforma em instâncias do ambiente. Elas são organizadas por namespace.

$ /opt/elasticbeanstalk/bin/get-config optionsettings
{"aws:elasticbeanstalk:application:environment":{"JDBC_CONNECTION_STRING":""},"aws:elasticbeanstalk:container:tomcat:jvmoptions":{"JVM Options":"","Xms":"256m","Xmx":"256m"},"aws:elasticbeanstalk:environment:proxy":{"ProxyServer":"nginx","StaticFiles":[""]},"aws:elasticbeanstalk:healthreporting:system":{"SystemType":"enhanced"},"aws:elasticbeanstalk:hostmanager":{"LogPublicationControl":"false"}}

Para retornar o valor de uma opção de configuração específica, use a opção --namespace (-n) para especificar um namespace, e a opção --option-name (-o) para especificar o nome de uma opção.

$ /opt/elasticbeanstalk/bin/get-config optionsettings -n aws:elasticbeanstalk:container:php:phpini -o memory_limit
256M

O comando get-config environment retorna um objeto que contém uma lista de propriedades do ambiente. Elas incluem propriedades configuradas pelo usuário e aquelas fornecidas pelo Elastic Beanstalk.

$ /opt/elasticbeanstalk/bin/get-config environment
{"JDBC_CONNECTION_STRING":"","RDS_PORT":"3306","RDS_HOSTNAME":"anj9aw1b0tbj6b.cijbpanmxz5u.us-west-2.rds.amazonaws.com","RDS_USERNAME":"testusername","RDS_DB_NAME":"ebdb","RDS_PASSWORD":"testpassword1923851"}

Por exemplo, o Elastic Beanstalk fornece propriedades de ambiente para conexão a uma instância de banco de dados integrada do Amazon RDS (por exemplo, RDS_HOSTNAME). Essas propriedades de conexão do RDS aparecem na saída do get-config environment. No entanto, elas não aparecem na saída do get-config optionsettings. Isso ocorre porque elas não foram definidas nas opções de configuração.

Para retornar uma propriedade específica do ambiente, use a opção --key (-k) para especificar uma chave de propriedade.

$ /opt/elasticbeanstalk/bin/get-config environment -k TESTPROPERTY
testvalue

O comando get-config container retorna um objeto que lista valores de configuração de ambiente e plataforma para instâncias de ambiente.

O exemplo a seguir mostra a saída do comando em um ambiente Tomcat do Amazon Linux 2.

$ /opt/elasticbeanstalk/bin/get-config container
{"common_log_list":["/var/log/eb-engine.log","/var/log/eb-hooks.log"],"default_log_list":["/var/log/nginx/access.log","/var/log/nginx/error.log"],"environment_name":"myenv-1da84946","instance_port":"80","log_group_name_prefix":"/aws/elasticbeanstalk","proxy_server":"nginx","static_files":[""],"xray_enabled":"false"}

Para retornar o valor de uma chave específica, use a opção --key (-k) para especificar a chave.

$ /opt/elasticbeanstalk/bin/get-config container -k environment_name
myenv-1da84946

O comando get-config addons retorna um objeto que contém informações de configuração adicionadas ao complemento do ambiente. Use-o para recuperar a configuração de um banco de dados do Amazon RDS associado ao ambiente.

$ /opt/elasticbeanstalk/bin/get-config addons
{"rds":{"Description":"RDS Environment variables","env":{"RDS_DB_NAME":"ebdb","RDS_HOSTNAME":"ea13k2wimu1dh8i.c18mnpu5rwvg.us-east-2.rds.amazonaws.com","RDS_PASSWORD":"password","RDS_PORT":"3306","RDS_USERNAME":"user"}}}

É possível restringir o resultado de duas maneiras. Para recuperar valores de um complemento específico, use a opção --add-on (-a) para especificar o nome do complemento.

$ /opt/elasticbeanstalk/bin/get-config addons -a rds
{"Description":"RDS Environment variables","env":{"RDS_DB_NAME":"ebdb","RDS_HOSTNAME":"ea13k2wimu1dh8i.c18mnpu5rwvg.us-east-2.rds.amazonaws.com","RDS_PASSWORD":"password","RDS_PORT":"3306","RDS_USERNAME":"user"}}

Para retornar o valor de uma chave específica dentro de um complemento, adicione a opção --key (-k) para especificar a chave.

$ /opt/elasticbeanstalk/bin/get-config addons -a rds -k RDS_DB_NAME
ebdb

O comando get-config platformconfig retorna um objeto que contém informações de configuração da plataforma que são constantes para a versão da plataforma. A saída é a mesma em todos os ambientes que executam a mesma versão da plataforma. O objeto de saída do comando tem dois objetos incorporados:

  • GeneralConfig: contém informações constantes nas versões mais recentes de todas as ramificações de plataformas Amazon Linux 2 e Amazon Linux 2023.

  • PlatformSpecificConfig: contém informações que são constantes para a versão da plataforma e que são específicas para ela.

O exemplo a seguir mostra a saída do comando em um ambiente que usa o Tomcat 8.5 executando a ramificação da plataforma Corretto 11.

$ /opt/elasticbeanstalk/bin/get-config platformconfig
{"GeneralConfig":{"AppUser":"webapp","AppDeployDir":"/var/app/current/","AppStagingDir":"/var/app/staging/","ProxyServer":"nginx","DefaultInstancePort":"80"},"PlatformSpecificConfig":{"ApplicationPort":"8080","JavaVersion":"11","TomcatVersion":"8.5"}}

Para retornar o valor de uma chave específica, use a opção --key (-k) para especificar a chave. Essas chaves são exclusivas entre os dois objetos incorporados. Não é necessário especificar o objeto que contém a chave.

$ /opt/elasticbeanstalk/bin/get-config platformconfig -k AppStagingDir
/var/app/staging/

Opções de saída get-config

Use a opção --output para especificar o formato do objeto de saída. Os valores válidos são JSON (padrão) e YAML. Essa é uma opção global. Você deve especificá-la antes do nome do comando.

O exemplo a seguir retorna valores de opção de configuração no formato YAML.

$ /opt/elasticbeanstalk/bin/get-config --output YAML optionsettings
aws:elasticbeanstalk:application:environment:
  JDBC_CONNECTION_STRING: ""
aws:elasticbeanstalk:container:tomcat:jvmoptions:
  JVM Options: ""
  Xms: 256m
  Xmx: 256m
aws:elasticbeanstalk:environment:proxy:
  ProxyServer: nginx
  StaticFiles:
        - ""
aws:elasticbeanstalk:healthreporting:system:
  SystemType: enhanced
aws:elasticbeanstalk:hostmanager:
  LogPublicationControl: "false"

pkg-repo

nota

A ferramenta pkg-repo não está disponível para ambientes baseados em plataformas Amazon Linux 2023. No entanto, você pode aplicar atualizações de pacote e sistema operacional manualmente a uma instância AL2023. Para obter mais informações, consulte Gerenciamento de pacotes e atualizações do sistema operacional no Guia do usuário do Amazon Linux 2023

Em algumas circunstâncias urgentes, talvez seja necessário atualizar suas instâncias do Amazon EC2 com um patch de segurança do Amazon Linux 2 que ainda não foi lançado com as versões necessárias da plataforma do Elastic Beanstalk. Você não pode executar uma atualização manual em seus ambientes do Elastic Beanstalk por padrão. Isso ocorre porque as versões da plataforma estão bloqueadas em uma versão específica do repositório do Amazon Linux 2. Esse bloqueio garante que as instâncias executem versões de software compatíveis e consistentes. Para casos urgentes, a ferramenta pkg-repo permite uma solução alternativa para atualizar manualmente os pacotes yum no Amazon Linux 2 se você precisar instalá-los em um ambiente antes de serem lançados em uma nova versão da plataforma do Elastic Beanstalk.

A ferramenta pkg-repo das plataformas Amazon Linux 2 permitem desbloquear os repositórios dos pacotes yum. Em seguida, você pode executar manualmente um yum update para um patch de segurança. Por outro lado, você pode seguir a atualização usando a ferramenta para bloquear os repositórios de pacotes yum para evitar atualizações adicionais. A ferramenta pkg-repo está disponível no diretório /opt/elasticbeanstalk/bin/pkg-repo de todas as instâncias do EC2 no seu ambiente do Elastic Beanstalk.

Alterações usando a ferramenta pkg-repo são feitas somente na instância do EC2 em que a ferramenta é usada. Elas não afetam outras instâncias nem impedem atualizações futuras do ambiente. Os exemplos fornecidos posteriormente neste tópico explicam como aplicar as alterações em todas as instâncias chamando os comandos pkg-repo de scripts e arquivos de configuração.

Atenção

Nós não recomendamos essa ferramenta para a maioria dos usuários. Quaisquer alterações manuais aplicadas a uma versão desbloqueada da plataforma é considerada fora de banda. Essa opção só é viável para os usuários em circunstâncias urgentes que podem aceitar os seguintes riscos:

  • Não é possível garantir que as versões dos pacotes sejam consistentes entre todas as instâncias de seus ambientes.

  • Não há garantias de que ambientes modificados usando-se a ferramenta pkg-repo funcionem corretamente. Eles não foram testados e verificados em plataformas compatíveis com o Elastic Beanstalk.

Recomendamos a aplicação de práticas recomendadas que incluem planos de teste e backout. Para ajudar a aplicar as práticas recomendadas, você pode usar o console do Elastic Beanstalk e a CLI do EB para clonar um ambiente e trocar URLs do ambiente. Para obter mais informações sobre como usar essas operações, consulte Implantações azuis/verdes no capítulo Gerenciar ambientes deste guia.

Se você planeja editar manualmente os arquivos de configuração do repositório yum, execute a ferramenta pkg-repo primeiro. A ferramenta pkg-repo talvez não funcione como o esperado em um ambiente Amazon Linux 2 com arquivos de configuração do repositório yum editados manualmente. Isso ocorre porque a ferramenta pode não reconhecer as alterações de configuração.

Para obter mais informações sobre o repositório de pacotes Amazon Linux, consulte o tópico Repositório de pacotes no Guia do usuário do Amazon EC2.

comandos pkg-repo

Use a sintaxe a seguir para executar os comandos da ferramenta pkg-repo.

$ /opt/elasticbeanstalk/bin/pkg-repo command [options]

Os comandos de pkg-repo são os seguintes:

  • lock: bloqueia os repositórios de pacotes yum em uma versão específica

  • unlock: desbloqueia os repositórios de pacotes yum de uma versão específica

  • status: lista todos os repositórios de pacotes yum e o status de bloqueio atual deles

  • help: mostra ajuda geral ou ajuda para um comando

As opções a seguir se aplicam aos seguintes comandos.

  • lock, unlock e status - opções: -h,--help, ou nenhum (padrão).

  • help – opções: lock, unlock, status ou nenhum (padrão).

O exemplo a seguir executa o comando unlock:

$ sudo /opt/elasticbeanstalk/bin/pkg-repo unlock
Amazon Linux 2 core package repo successfully unlocked
Amazon Linux 2 extras package repo successfully unlocked

O exemplo a seguir executa o comando lock:

$ sudo /opt/elasticbeanstalk/bin/pkg-repo lock
Amazon Linux 2 core package repo successfully locked
Amazon Linux 2 extras package repo successfully locked

O exemplo a seguir executa o comando status:

$ sudo /opt/elasticbeanstalk/bin/pkg-repo status
Amazon Linux 2 core package repo is currently UNLOCKED
Amazon Linux 2 extras package repo is currently UNLOCKED

O exemplo a seguir executa o comando help para o comando lock.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo help lock

O exemplo a seguir executa o comando help para a ferramenta pkg-repo.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo help

É possível testar pkg-repo usando SSH para se conectar a uma instância no ambiente do Elastic Beanstalk. Uma opção de SSH é o comando CLI do EB eb ssh.

nota

A ferramenta pkg-repo requer privilégios de usuário root para execução. Se você receber um erro de permissão de acesso, execute o comando novamente em sudo.

Você não precisa adicionar sudo ao usar a ferramenta nos scripts ou arquivos de configuração que você implanta no seu ambiente. O Elastic Beanstalk executa todos os seus scripts como o usuário raiz.

exemplos de pkg-repo

A seção anterior fornece exemplos de linha de comando para testes em uma instância do EC2 individual de um ambiente do Elastic Beanstalk. Essa abordagem pode ser útil para testes. No entanto, ela atualiza apenas uma instância por vez, portanto, não é prático aplicar alterações em todas as instâncias em um ambiente.

Uma abordagem mais pragmática é usar scripts de hook de plataforma ou um arquivo de configuração .ebextensions para aplicar as alterações em todas as instâncias de forma consistente.

O exemplo a seguir chama o pkg-repo de um arquivo de configuração da pasta .ebextensions. O Elastic Beanstalk executa os comandos no arquivo update_package.config quando você implanta seu pacote-fonte de aplicação.

.ebextensions
└── update_package.config

Para receber a versão mais recente do pacote de docker, essa configuração especifica o pacote de docker no comando yum update.

### update_package.config ###

commands:
  update_package:
    command: |
      /opt/elasticbeanstalk/bin/pkg-repo unlock
      yum update docker -y
      /opt/elasticbeanstalk/bin/pkg-repo lock
      yum clean all -y
      rm -rf /var/cache/yum

Essa configuração não especifica nenhum pacote no comando yum update. A consequência é que todas as atualizações disponíveis são aplicadas.

### update_package.config ###

commands:
  update_package:
    command: |
      /opt/elasticbeanstalk/bin/pkg-repo unlock
      yum update -y
      /opt/elasticbeanstalk/bin/pkg-repo lock
      yum clean all -y
      rm -rf /var/cache/yum

O exemplo a seguir chama o pkg-repo de um script bash como um hook de plataforma. O Elastic Beanstalk executa o arquivo de script update_package.sh localizado no subdiretório prebuild.

.platform
└── hooks
    └── prebuild
        └── update_package.sh

Para receber a versão mais recente do pacote de docker, esse script especifica o pacote do docker no comando yum update. Se o nome do pacote for omitido, todas as atualizações disponíveis serão aplicadas. O exemplo do arquivo de configuração anterior demonstra isso.

### update_package.sh ###

#!/bin/bash

/opt/elasticbeanstalk/bin/pkg-repo unlock
yum update docker -y
/opt/elasticbeanstalk/bin/pkg-repo lock
yum clean all -y
rm -rf /var/cache/yum

download-source-bundle (Somente Amazon Linux AMI)

Nas ramificações de plataforma da AMI do Amazon Linux (anteriores ao Amazon Linux 2), o Elastic Beanstalk fornece uma ferramenta adicional, que é download-source-bundle. Use essa ferramenta para baixar o código-fonte da sua aplicação durante a implantação da plataforma. A ferramenta está disponível em /opt/elasticbeanstalk/bin/download-source-bundle.

O script de exemplo 00-unzip.sh está localizado na pasta appdeploy/pre em instâncias do ambiente. Ele demonstra como usar download-source-bundle para baixar o código-fonte da aplicação para a pasta /opt/elasticbeanstalk/deploy/appsource durante a implantação.