Configurar ambientes do Docker

Existem várias maneiras de configurar o comportamento do ambiente do Docker do Elastic Beanstalk.

nota

Se o ambiente do Elastic Beanstalk usar uma versão da plataforma do Amazon Linux AMI Docker (que precede o Amazon Linux 2), leia as informações adicionais no Configuração do Docker na AMI do Amazon Linux (que precede o Amazon Linux 2).

Configurar o software em ambientes do Docker

É possível usar o console do Elastic Beanstalk para configurar o software em execução nas instâncias do ambiente.

Como configurar o ambiente do Docker no console do Elastic Beanstalk

1. Abra o console do Elastic Beanstalk e, na lista Regions (Regiões), selecione a sua Região da AWS.

2. No painel de navegação, selecione Ambientes e selecione o nome do ambiente na lista.

   nota

   Se você tiver muitos ambientes, use a barra de pesquisa para filtrar a lista de ambientes.

3. No painel de navegação, escolha Configuration (Configuração).

4. Na categoria de configuração Updates, monitoring, and logging (Atualizações, monitoramento e logs), escolha Edit (Editar).

5. Faça as alterações necessárias na configuração.

6. Para salvar as alterações, escolha Apply (Aplicar) na parte inferior da página.

Para obter informações sobre como definir configurações de software em qualquer ambiente, consulte Propriedades de ambientes e outras configurações de software. As seções a seguir abordam informações específicas do Docker.

Opções de contêiner

A seção Container options (Opções de contêiner) tem opções específicas da plataforma. Para ambientes do Docker, isso permite que você escolha se o ambiente incluirá ou não o servidor de proxy Nginx.

Ambientes com Docker Compose

Se gerenciar seu ambiente do Docker com o Docker Compose, o Elastic Beanstalk assumirá que você executa um servidor de proxy como um contêiner. Portanto, ele usa como padrão None (Nenhum) para a configuração Proxy server (Servidor de proxy) e o Elastic Beanstalk não fornece uma configuração NGINX.

nota

Mesmo que você selecione NGINX como servidor de proxy, essa configuração será ignorada em um ambiente com Docker Compose. A configuração Proxy server (Servidor de proxy) ainda é padrão para None (Nenhum).

Como o proxy do servidor Web NGINX está desabilitado para a plataforma Docker no Amazon Linux 2 com o Docker Compose, é necessário seguir as instruções para gerar logs para relatórios de integridade aprimorada. Para obter mais informações, consulte Gerar logs para a geração de relatórios de integridade aprimorados (Docker Compose).

Propriedades de ambiente e variáveis de ambiente

A seção Environment Properties (Propriedades de ambiente) permite que você especifique definições de configuração do ambiente nas instâncias do Amazon Elastic Compute Cloud (Amazon EC2) que estão executando a aplicação. As propriedades de ambiente são passadas para o aplicativo como pares de chave-valor. Em um ambiente do Docker, o Elastic Beanstalk transmite propriedades de ambiente para contêineres como variáveis de ambiente.

O código do aplicativo em execução em um contêiner pode se referir à variável de um ambiente pelo nome e ler seu valor. O código-fonte que lê essas variáveis de ambiente varia de acordo com a linguagem de programação. É possível encontrar instruções para ler valores de variáveis de ambiente nas linguagens de programação compatíveis com as plataformas gerenciadas do Elastic Beanstalk no respectivo tópico de plataforma. Para obter uma lista de links para esses tópicos, consulte Propriedades de ambientes e outras configurações de software.

Ambientes com Docker Compose

Se você gerenciar seu ambiente do Docker com o Docker Compose, deverá fazer alguma configuração adicional para recuperar as variáveis de ambiente nos contêineres. Para que os executáveis em execução no contêiner acessem essas variáveis de ambiente, será necessário fazer referência a eles no docker-compose.yml. Para mais informações, consulte Fazer referência a variáveis de ambiente em contêineres.

Fazer referência a variáveis de ambiente em contêineres

Se você estiver usando a ferramenta Docker Compose na plataforma Docker do Amazon Linux 2, o Elastic Beanstalk gerará um arquivo de ambiente do Docker Compose chamado .env no diretório raiz do projeto de aplicação. Esse arquivo armazena as variáveis de ambiente configuradas para Elastic Beanstalk.

nota

Se você incluir um arquivo .env no pacote de aplicações, o Elastic Beanstalk não gerará um arquivo .env.

Para que um contêiner faça referência às variáveis de ambiente definidas no Elastic Beanstalk, é necessário seguir uma ou ambas as abordagens de configuração.

• Adicione o arquivo .env gerado pelo Elastic Beanstalk à opção de configuração env_file no arquivo docker-compose.yml.

• Defina as variáveis de ambiente diretamente no arquivo docker-compose.yml.

Os arquivos a seguir fornecem um exemplo. O arquivo demonstrativo docker-compose.yml mostra as duas abordagens.

• Se você definir as propriedades de ambiente DEBUG_LEVEL=1 e LOG_LEVEL=error, o Elastic beanstalk gerará o seguinte arquivo .env:

  DEBUG_LEVEL=1
  LOG_LEVEL=error

• Neste arquivo docker-compose.yml, a opção de configuração env_file aponta para o arquivo .env e também define a variável de ambiente DEBUG=1 diretamente no arquivo docker-compose.yml.

  services:
    web:
      build: .
      environment:
        - DEBUG=1
      env_file:
        - .env

Observações

• Se você definir a mesma variável de ambiente nos dois arquivos, a variável definida no arquivo docker-compose.yml terá precedência maior do que a variável definida no arquivo .env.

• Tenha cuidado para não deixar espaços entre o sinal de igual (=) e o valor atribuído à sua variável para evitar que espaços sejam adicionados à string.

Para saber mais sobre variáveis de ambiente no Docker Compose, consulte Variáveis de ambiente no Compose

Usando o recurso de interpolação para variáveis de ambiente (Docker Compose)

A partir de 28 de julho de 2023, data de lançamento da plataforma, a ramificação da plataforma Docker Amazon Linux 2 oferece o recurso de interpolação Docker Compose. Com esse recurso, os valores em um arquivo do Compose podem ser definidos por variáveis e interpolados em tempo de execução. Para obter mais informações sobre esse recurso, consulte Interpolação no site de documentação do Docker.

Importante

Se desejar usar esse atributo, com suas aplicações esteja ciente de que precisará implementar uma abordagem que use hooks de plataforma.

Isso é necessário devido a uma mitigação que implementamos no mecanismo da plataforma. Essa mitigação garante compatibilidade com as versões anteriores para clientes que não conhecem o novo atributo de interpolação e têm aplicações existentes que usam variáveis de ambiente com o caractere $. O mecanismo de plataforma atualizado escapa da interpolação por padrão substituindo o caractere $ por caracteres $$.

Veja a seguir um exemplo de um script de hook de plataforma que é possível configurar para permitir o uso do recurso de interpolação.

#!/bin/bash

: '
example data format in .env file
key1=value1
key2=value2
'
envfile="/var/app/staging/.env"
tempfile=$(mktemp)

while IFS= read -r line; do
  # split each env var string at '='
  split_str=(${line//=/ })
  if [ ${#split_str[@]} -eq 2 ]; then
    # replace '$$' with '$'
    replaced_str=${split_str[1]//\$\$/\$}
    # update the value of env var using ${replaced_str}
    line="${split_str[0]}=${replaced_str}"
  fi
  # append the updated env var to the tempfile
  echo "${line}" ≫"${tempfile}"
done < "${envfile}"
# replace the original .env file with the tempfile
mv "${tempfile}" "${envfile}"

Coloque os hooks da plataforma em ambos os diretórios:

• .platform/confighooks/predeploy/

• .platform/hooks/predeploy/

Para obter mais informações, consulte Hooks de plataforma no tópico Estender plataformas Linux deste guia.

Gerar logs para a geração de relatórios de integridade aprimorados (Docker Compose)

O agente de integridade do Elastic Beanstalk fornece métricas de integridade do sistema operacional e da aplicação para ambientes do Elastic Beanstalk. Ele se baseia em formatos de log do servidor da Web que retransmitem informações em um formato específico.

O Elastic Beanstalk pressupõe que você execute um proxy de servidor da Web como um contêiner. Como resultado, o proxy do servidor da Web NGINX é desativado para ambientes do Docker que executam o Docker Compose. É necessário configurar o servidor para gravar logs no local e no formato usados pelo agente de integridade do Elastic Beanstalk. Isso permite que você faça uso completo dos relatórios de integridade aprimorados, mesmo que o proxy do servidor da Web esteja desabilitado.

Para obter instruções sobre como fazer isso, consulte Configuração do log de servidor web

Registro em log personalizado do contêiner do Docker (Docker Compose)

Para solucionar problemas de forma eficiente e monitorar os serviços em contêineres, é possível solicitar logs de instância do Elastic Beanstalk por meio do console de gerenciamento de ambiente ou da CLI do EB. Os logs de instância são compostos de logs de pacote e logs de cauda, combinados e empacotados para permitir que você visualize logs e eventos recentes de maneira eficiente e direta.

O Elastic Beanstalk cria diretórios de logs na instância de contêiner, um para cada serviço definido no arquivo docker-compose.yml, em /var/log/eb-docker/containers/<service name>. Se você estiver usando o recurso Docker Compose na plataforma Docker do Amazon Linux 2, poderá montar esses diretórios no local dentro da estrutura do arquivo de contêiner onde os logs são gravados. Quando você monta diretórios de logs para gravar dados de log, o Elastic Beanstalk pode coletar dados de log desses diretórios.

Se as aplicações estiverem em uma plataforma Docker que não esteja usando o Docker Compose, você poderá seguir o procedimento padrão descrito em Registro em log personalizado do contêiner do Docker (Docker Compose).

Como configurar os arquivos de logs do seu serviço para serem arquivos de cauda e logs de pacote recuperáveis

1. Edite o arquivo docker-compose.yml.

2. Na chave volumes do seu serviço, adicione uma montagem de ligação deste modo:

   "${EB_LOG_BASE_DIR}/<service name>:<log directory inside container>

   No arquivo demonstrativo docker-compose.yml abaixo:

   • nginx-proxy é <nome do serviço>

   • /var/log/nginx é <diretório de logs dentro do contêiner>

   services:
     nginx-proxy:
       image: "nginx"
       volumes:
         - "${EB_LOG_BASE_DIR}/nginx-proxy:/var/log/nginx"

• O diretório var/log/nginx contém os logs do serviço nginx-proxy no contêiner e será mapeado para o diretório /var/log/eb-docker/containers/nginx-proxy no host.

• Todos os logs nesse diretório agora são recuperáveis como logs finais e de pacote por meio da funcionalidade de solicitação de logs de instância do Elastic Beanstalk.

Observações

• $ {EB_LOG_BASE_DIR} é uma variável de ambiente definida pelo Elastic Beanstalk com o valor /var/log/eb-docker/containers.

• O Elastic Beanstalk cria automaticamente o diretório /var/log/eb-docker/containers/<service name> para cada serviço no arquivo docker-compose.yml.

Imagens de Docker

As ramificações da plataforma Docker e Docker gerenciado pelo ECS para o Elastic Beanstalk são compatíveis com o uso de imagens do Docker armazenadas em um repositório de imagens online público ou privado.

Especifique as imagens por nome em Dockerrun.aws.json. Observe as seguintes convenções:

• As imagens em repositórios oficiais no Docker Hub usam um único nome (por exemplo, ubuntu ou mongo).

• As imagens em outros repositórios no Docker Hub são qualificadas com um nome de organização (por exemplo, amazon/amazon-ecs-agent).

• As imagens em outros repositórios online são ainda mais qualificadas por um nome de domínio (por exemplo, quay.io/assemblyline/ubuntu ou account-id.dkr.ecr.us-east-2.amazonaws.com/ubuntu:trusty).

Para ambientes que usam apenas a plataforma Docker, também é possível criar sua própria imagem durante a criação do ambiente com um Dockerfile. Para mais detalhes, consulte Criar imagens personalizadas com um Dockerfile. A plataforma Docker de vários contêineres não é compatível com essa funcionalidade.

Usar imagens de um repositório do Amazon ECR

É possível armazenar suas imagens de Docker personalizadas na AWS com o Amazon Elastic Container Registry (Amazon ECR). Quando você armazena suas imagens de Docker no Amazon ECR, o Elastic Beanstalk autentica automaticamente o registro do Amazon ECR com o perfil da instância de seu ambiente para que não seja necessário gerenciar um arquivo de autenticação e fazer upload dele no Amazon Simple Storage Service (Amazon S3).

No entanto, é necessário fornecer suas instâncias com permissão para acessar as imagens em seu repositório do Amazon ECR adicionando permissões ao perfil da instância de seu ambiente. É possível anexar a política gerenciada AmazonEC2ContainerRegistryReadOnly ao perfil da instância para dar acesso somente de leitura a todos os repositórios do Amazon ECR em sua conta. Alternativamente, você pode conceder acesso ao repositório único usando o modelo a seguir para criar uma política personalizada:

{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowEbAuth",
        "Effect": "Allow",
        "Action": [
          "ecr:GetAuthorizationToken"
        ],
        "Resource": [
          "*"
        ]
      },
      {
        "Sid": "AllowPull",
        "Effect": "Allow",
        "Resource": [
          "arn:aws:ecr:us-east-2:account-id:repository/repository-name"
        ],
        "Action": [
          "ecr:GetAuthorizationToken",
          "ecr:BatchCheckLayerAvailability",
          "ecr:GetDownloadUrlForLayer",
          "ecr:GetRepositoryPolicy",
          "ecr:DescribeRepositories",
          "ecr:ListImages",
          "ecr:BatchGetImage"
        ]
      }
    ]
  }

Substitua o nome de recurso da Amazon (ARN) na política acima pelo ARN de seu repositório.

Em seu arquivo Dockerrun.aws.json, faça referência à imagem pelo URL. Para a plataforma Docker, o URL deve ser inserido na definição de Image:

  "Image": {
      "Name": "account-id.dkr.ecr.us-east-2.amazonaws.com/repository-name:latest",
      "Update": "true"
    },

Para a plataforma Docker de vários contêineres, use a chave image em um objeto de definição do contêiner:

"containerDefinitions": [
        {
        "name": "my-image",
        "image": "account-id.dkr.ecr.us-east-2.amazonaws.com/repository-name:latest",

Usar imagens de um repositório privado

Para usar uma imagem de Docker em um repositório privado hospedado por um registro online, você deve fornecer um arquivo de autenticação que contenha as informações necessárias para autenticar no registro.

Gere um arquivo de autenticação com o comando docker login. Para repositórios no Docker Hub, execute docker login:

$ docker login

Para outros registros, inclua o URL do servidor de registro:

$ docker login registry-server-url

nota

Se o ambiente do Elastic Beanstalk usar uma versão da plataforma Docker da AMI do Amazon Linux (que precede o Amazon Linux 2), leia as informações adicionais em Configuração do Docker na AMI do Amazon Linux (que precede o Amazon Linux 2).

Faça upload de uma cópia chamada .dockercfg do arquivo de autenticação em um bucket seguro do Amazon S3. O bucket do Amazon S3 deve ser hospedado na mesma região da AWS do ambiente que o está usando. O Elastic Beanstalk não pode fazer download de arquivos de um bucket do Amazon S3 hospedado em outras regiões. Conceda permissões para a operação s3:GetObject à função do IAM no perfil da instância. Para obter mais detalhes, consulte Gerenciar perfis de instância do Elastic Beanstalk.

Inclua as informações do bucket do Amazon S3 no parâmetro Authentication (v1) ou authentication (v2) no arquivo Dockerrun.aws.json.

Para obter mais informações sobre o formato de Dockerrun.aws.json para ambientes do Docker, consulte Configuração do Docker. Para informações sobre ambientes de vários contêineres, consulte Configuração do Docker gerenciado pelo ECS.

Para obter mais informações sobre o arquivo de autenticação, consulte Store images on Docker Hub e docker login no site do Docker.

Configurar atualizações gerenciadas para ambientes do Docker

Com as atualizações gerenciadas de plataforma, é possível configurar o ambiente para ser atualizado automaticamente para a versão mais recente de uma plataforma em um agendamento.

No caso de ambientes do Docker, pode ser conveniente decidir se uma atualização automática de plataforma deverá acontecer entre versões do Docker, quando a nova versão da configuração da plataforma inclui uma nova versão do Docker. O Elastic Beanstalk é compatível com atualizações de plataforma gerenciada nas versões do Docker ao atualizar a partir de um ambiente que execute uma versão da plataforma Docker mais recente do que a 2.9.0. Quando uma nova versão de plataforma inclui uma nova versão do Docker, o Elastic Beanstalk incrementa o número da versão de atualização secundária. Portanto, para permitir as atualizações gerenciadas de plataforma entre versões do Docker, habilite essas atualizações para atualizações de versão secundária e de patch. Para evitar as atualizações gerenciadas de plataforma entre versões do Docker, habilite essas atualizações para aplicar somente atualizações de versão de patch.

Por exemplo, o seguinte arquivo de configuração habilita as atualizações gerenciadas de Plataforma às 9h UTC toda terça-feira para atualizações de versão secundária e de patch, permitindo as atualizações gerenciadas entre versões do Docker:

exemplo .ebextensions/managed-platform-update.config

option_settings:
  aws:elasticbeanstalk:managedactions:
    ManagedActionsEnabled: true
    PreferredStartTime: "Tue:09:00"
  aws:elasticbeanstalk:managedactions:platformupdate:
    UpdateLevel: minor

Para ambientes que executam versões de plataforma do Docker 2.9.0 ou anterior, o Elastic Beanstalk nunca executará as atualizações gerenciadas de plataforma se a nova versão da configuração da plataforma incluir uma nova versão do Docker.

Namespaces de configuração do Docker

Você pode usar um arquivo de configuração para definir opções de configuração e executar outras tarefas de configuração de instância durante implantações. As opções de configuração podem ser definidas pelo serviço Elastic Beanstalk ou pela plataforma utilizada, e são organizadas em namespaces.

nota

Essas informações só se aplicam ao ambiente do Docker que não esteja executando o Docker Compose. Essa opção tem um comportamento diferente com ambientes do Docker que executam o Docker Compose. Para obter mais informações sobre serviços proxy com o Docker Compose, consulte Opções de contêiner.

A plataforma Docker é compatível com as opções nos namespaces a seguir, além das opções compatíveis com todos os ambientes do Elastic Beanstalk:

• aws:elasticbeanstalk:environment:proxy: escolha o servidor de proxy para o ambiente. O Docker oferece suporte à execução com o servidor de proxy Nginx ou nenhum servidor.

O arquivo de configuração de exemplo a seguir configura um ambiente do Docker para não executar nenhum servidor de proxy.

exemplo .ebextensions/docker-settings.config

option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: none

Configuração do Docker na AMI do Amazon Linux (que precede o Amazon Linux 2)

Se o ambiente Docker do Elastic Beanstalk usar uma versão da plataforma AMI do Amazon Linux (que precede o Amazon Linux 2), leia as informações adicionais nesta seção.

Usar um arquivo de autenticação para um repositório privado

Essas informações são relevantes se você estiver usando imagens de um repositório privado. A partir do Docker versão 1.7, o comando docker login alterou o nome do arquivo de autenticação e o formato do arquivo. As versões da plataforma Docker da AMI do Amazon Linux (que precede o Amazon Linux 2) exigem o arquivo de configuração de formato ~/.dockercfg mais antigo.

Com o Docker versão 1.7 e posterior, o comando docker login cria o arquivo de autenticação em ~/.docker/config.json no formato a seguir.

{
    "auths":{
      "server":{
        "auth":"key"
      }
    }
  }

Com o Docker versão 1.6.2 e anterior, o comando docker login cria o arquivo de autenticação em ~/.dockercfg no formato a seguir.

{
    "server" :
    {
      "auth" : "auth_token",
      "email" : "email"
    }
  }

Para converter um arquivo config.json, remova a chave auths externa, adicione uma chave email e simplifique o documento JSON para que corresponda ao formato antigo.

Nas versões da plataforma Docker do Amazon Linux 2, o Elastic Beanstalk usa o nome e o formato mais recentes do arquivo de autenticação. Se você estiver usando uma versão da plataforma Docker do Amazon Linux 2, será possível usar o arquivo de autenticação criado pelo comando docker login sem nenhuma conversão.

Configurar volumes de armazenamento adicionais

Para melhorar a performance na AMI do Amazon Linux, o Elastic Beanstalk configura dois volumes de armazenamento do Amazon EBS para as instâncias do Amazon EC2 do ambiente Docker. Além do volume raiz provisionado para todos os ambientes do Elastic Beanstalk, um segundo volume de 12 GB chamado xvdcz é provisionado para armazenamento de imagens em ambientes do Docker.

Se você precisar de mais espaço de armazenamento ou de mais IOPS para imagens de Docker, pode personalizar o volume de armazenamento de imagens usando a opção de configuração BlockDeviceMapping no namespace aws:autoscaling:launchconfiguration.

Por exemplo, o seguinte arquivo de configuração aumenta o tamanho do volume de armazenamento para 100 GB com 500 IOPS provisionadas:

exemplo .ebextensions/blockdevice-xvdcz.config

option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:100::io1:500

Se você usar a opção BlockDeviceMappings para configurar volumes adicionais para seu aplicativo, inclua um mapeamento para xvdcz a fim de garantir que ele seja criado. O exemplo a seguir configura dois volumes, o volume de armazenamento de imagens xvdcz com as configurações padrão e um volume de aplicativo adicional de 24 GB chamado sdh:

exemplo .ebextensions/blockdevice-sdh.config

option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:12:true:gp2,/dev/sdh=:24

nota

Quando você altera as configurações nesse namespace, o Elastic Beanstalk substitui todas as instâncias no ambiente por instâncias que executam a nova configuração. Para mais detalhes, consulte Alterações de configuração.