Estender as plataformas Linux do Elastic Beanstalk - AWS Elastic Beanstalk

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á.

Estender as plataformas Linux do Elastic Beanstalk

As plataformas Linux do AWS Elastic Beanstalk oferecem muitas funcionalidades de imediato para oferecer suporte ao desenvolvimento e execução de aplicações. Quando necessário, você pode estender as plataformas de várias maneiras para configurar opções, instalar software, adicionar arquivos e executar comandos, fornecer instruções de compilação e runtime e adicionar scripts de inicialização executados em vários estágios de provisionamento das instâncias do Amazon Elastic Compute Cloud (Amazon EC2) do seu ambiente.

Algumas plataformas permitem que você personalize a maneira como cria ou prepara seu aplicativo e especifique os processos que executam seu aplicativo. Cada tópico de plataforma individual menciona especificamente Buildfile e/ou Procfile se a plataforma oferecer suporte a eles. Procure sua plataforma específica em Plataformas do Elastic Beanstalk.

Para todas as plataformas compatíveis, a sintaxe e a semântica são idênticas e descritas nesta página. Tópicos individuais da plataforma mencionam o uso específico desses arquivos para criar e executar aplicativos em suas respectivas linguagens.

Buildfile

Para especificar um comando personalizado de compilação e configuração para o aplicativo, coloque um arquivo chamado Buildfile no diretório raiz da origem do aplicativo. O nome do arquivo diferencia maiúsculas de minúsculas. Use a seguinte sintaxe para o Buildfile.

<process_name>: <command>

O comando no Buildfile deve corresponder à expressão regular: ^[A-Za-z0-9_-]+:\s*[^\s].*$.

O Elastic Beanstalk não monitora a aplicação executada com um Buildfile. Use um Buildfile para comandos que são executados por breves períodos e são encerrados após a conclusão das tarefas. Para processos de aplicativo de longa execução que não devem ser encerrados, use o Procfile.

Todos os caminhos no Buildfile são relativos à raiz do pacote de origem. No seguinte exemplo de um Buildfile, o build.sh é um script de shell localizado na raiz do pacote de origem.

exemplo Buildfile
make: ./build.sh

Se você quiser fornecer etapas de compilação personalizadas, recomendamos que você use os hooks de plataforma predeploy para qualquer coisa, exceto os comandos mais simples, em vez de um Buildfile. Os hooks de plataforma permitem scripts mais avançados e melhor tratamento de erros. Os hooks de plataforma são descritos na próxima seção.

Procfile

Para especificar comandos personalizados para iniciar e executar o aplicativo, coloque um arquivo chamado Procfile no diretório raiz da origem do aplicativo. O nome do arquivo diferencia maiúsculas de minúsculas. Use a seguinte sintaxe para o Procfile. Você pode especificar um ou mais comandos.

<process_name1>: <command1> <process_name2>: <command2> ...

Cada linha no Procfile deve corresponder à expressão regular: ^[A-Za-z0-9_-]+:\s*[^\s].*$.

Use um Procfile para processos de aplicações de longa execução que não devem ser fechadas. O Elastic Beanstalk espera que os processos sejam executados a partir do Procfile para serem executados continuamente. O Elastic Beanstalk monitora esses processos e reinicia qualquer processo que seja encerrado. Para processos de curta execução, use um Buildfile.

Todos os caminhos no Procfile são relativos à raiz do pacote de origem. O exemplo do Procfile a seguir define três processos. O primeiro, chamado web no exemplo, é o principal aplicativo web.

exemplo Procfile
web: bin/myserver cache: bin/mycache foo: bin/fooapp

O Elastic Beanstalk configura o servidor de proxy para encaminhar solicitações à sua aplicação Web principal na porta 5000, e esse número de porta pode ser configurado. Um uso comum para um Procfile é passar esse número de porta para sua aplicação como um argumento de comando. Para obter detalhes sobre a configuração do proxy, expanda a seção Configuração de proxy reverso nesta página.

O Elastic Beanstalk captura streams de saída padrão e erros dos processos Procfile em arquivos de log. O Elastic Beanstalk fornece nomes aos arquivos de log após o processo e os armazena no /var/log. Por exemplo, o processo web do exemplo anterior gera logs chamados web-1.log e web-1.error.log para stdout e stderr, respectivamente.

Os hooks de plataforma são criados especificamente para estender a plataforma do ambiente. Eles são scripts personalizados e outros arquivos executáveis que são implantados como parte do código-fonte da aplicação, e são executados pelo Elastic Beanstalk durante vários estágios de provisionamento da instância.

nota

Os hooks de plataforma não são compatíveis com as versões da plataforma da AMI do Amazon Linux (anteriores ao Amazon Linux 2).

Hooks de plataforma de implantação de aplicações

Uma implantação de aplicação ocorre quando você fornece um novo pacote de origem para implantação ou quando faz uma alteração de configuração que exige o encerramento e a recriação de todas as instâncias do ambiente.

Para fornecer hooks de plataforma executados durante a implantação de uma aplicação, coloque os arquivos no diretório .platform/hooks do pacote de origem, em um dos seguintes subdiretórios.

  • prebuild: estes arquivos serão executados depois que o mecanismo da plataforma do Elastic Beanstalk fizer download e extrair o pacote de origem do aplicação, e antes de configurar a aplicação e o servidor Web.

    Os arquivos prebuild são executados depois da execução de comandos encontrados na seção commands, de qualquer arquivo de configuração, e antes da execução de comandos Buildfile.

  • predeploy: estes arquivos são executados depois que o mecanismo da plataforma do Elastic Beanstalk configura a aplicação e o servidor Web, e antes de implantá-los em seu local final de runtime.

    Os arquivos predeploy são executados depois da execução dos comandos encontrados na seção container_commands de qualquer arquivo de configuração, e antes da execução de comandos Procfile.

  • postdeploy: estes arquivos são executados depois que o mecanismo da plataforma do Elastic Beanstalk implanta a aplicação e o servidor de proxy.

    Esta é a última etapa do fluxo de trabalho de implantação.

Hooks de plataforma de implantação de configuração

Uma implantação de configuração ocorre quando você faz alterações de configuração que apenas atualizam instâncias do ambiente sem recriá-las. As atualizações de opção a seguir resultam em uma atualização da configuração.

Para fornecer hooks que são executados durante a implantação de uma configuração, coloque-os no diretório .platform/confighooks do pacote de origem. São aplicados os mesmos três subdiretórios que aqueles aplicados para os hooks de implantação de aplicações.

Mais sobre hooks de plataforma

Os arquivos de hook podem ser arquivos binários ou arquivos de script que começam com uma linha #! contendo seu caminho de interpretador, como #!/bin/bash. Todos os arquivos devem ter permissão de execução. Use chmod +x para definir a permissão de execução em seus arquivos de hook. Em todas as versões de plataforma baseadas no Amazon Linux 2023 e no Amazon Linux 2 lançadas a partir de 29 de abril de 2022, o Elastic Beanstalk concede automaticamente permissões de execução para todos os scripts de hook da plataforma. Nesse caso, não é necessário conceder manualmente as permissões de execução. Para obter uma lista dessas versões da plataforma, consulte as notas de versão do Linux de 29 de abril de 2022 no Guia de notas de versão do AWS Elastic Beanstalk.

O Elastic Beanstalk executa arquivos em cada um desses diretórios em ordem lexicográfica de nomes de arquivos. Todos os arquivos são executados como o usuário root. O diretório de trabalho atual (cwd) para hooks de plataforma é o diretório raiz do aplicativo. Para os arquivos prebuild e predeploy é o diretório de preparação do aplicativo, e para os arquivos postdeploy é o diretório atual do aplicativo. Se um dos arquivos falhar (terminar com um código de saída diferente de zero), a implantação será interrompida e falhará.

Um script de texto de hooks da plataforma pode falhar se contiver caracteres de quebra de linha retorno de carro/alimentação de linha (CRLF). Se um arquivo foi salvo em um host Windows e depois transferido para um servidor Linux, ele pode conter quebras de linha CRLF do Windows. Para plataformas lançadas a partir de 29 de dezembro de 2022, o Elastic Beanstalk converte automaticamente os caracteres CRLF do Windows em caracteres de quebra de linha alimentação de linha (LF) do Linux em arquivos de texto de hooks de plataforma. Se a aplicação for executada em qualquer plataforma Amazon Linux 2 lançada antes dessa data, você precisará converter os caracteres CRLF do Windows em caracteres LF do Linux. Uma forma de fazer isso é criar e salvar o arquivo de script em um host Linux. Ferramentas que convertem esses caracteres também estão disponíveis na internet.

Os arquivos de hook têm acesso a todas as propriedades de ambiente definidas nas opções da aplicação e às variáveis de ambiente do sistema HOME, PATH e PORT.

Para obter valores de variáveis de ambiente e outras opções de configuração nos scripts de hook de plataforma, é possível usar o utilitário get-config que o Elastic Beanstalk fornece em instâncias do ambiente. Para obter mais detalhes, consulte Ferramentas de script de plataforma.

Você pode adicionar arquivos de configuração ao diretório .ebextensions do código-fonte da sua aplicação para configurar vários aspectos do ambiente do Elastic Beanstalk. Entre outras coisas, os arquivos de configuração permitem personalizar software e outros arquivos nas instâncias do ambiente e executar comandos de inicialização nas instâncias. Para obter mais informações, consulte Personalizar software em servidores Linux.

Você também pode definir opções de configuração usando arquivos de configuração. Muitas das opções controlam o comportamento da plataforma, e algumas dessas opções são específicas da plataforma.

Nas plataformas do Amazon Linux 2 e Amazon Linux 2023, recomendamos o uso de hooks de plataforma, Buildfile e Procfile para configurar e executar código personalizado em suas instâncias de ambiente durante o provisionamento de instâncias. Esses mecanismos são descritos nas seções anteriores desta página. Você ainda pode usar comandos e os comandos de contêiner em arquivos de configuração .ebextensions, apesar de não ser fácil trabalhar com eles. Por exemplo, escrever scripts de comando dentro de um arquivo YAML pode ser um desafio do ponto de vista da sintaxe. Você ainda precisa usar arquivos de configuração .ebextensions para qualquer script que precise de uma referência a um recurso do AWS CloudFormation.

Todas as versões de plataformas Amazon Linux 2 e Amazon Linux 2023 usam o nginx como servidor de proxy reverso padrão. As plataformas Tomcat, Node.js, PHP e Python também oferecem suporte ao Apache HTTPD como uma alternativa. Para selecionar o Apache nessas plataformas, defina a opção ProxyServer no namespace aws:elasticbeanstalk:environment:proxy como apache. Todas as plataformas habilitam a configuração do servidor de proxy de forma uniforme, conforme descrito nesta seção.

nota

Nas versões da plataforma da AMI do Amazon Linux (anteriores ao Amazon Linux 2), talvez seja necessário configurar servidores de proxy de forma diferente. É possível encontrar esses detalhes legados nos respectivos tópicos de plataforma neste guia.

O Elastic Beanstalk configura o servidor de proxy nas instâncias do ambiente para encaminhar o tráfego da Web para a aplicação Web principal no URL raiz do ambiente; por exemplo, http://my-env.elasticbeanstalk.com.

Por padrão, o Elastic Beanstalk configura o proxy para encaminhar solicitações recebidas na porta 80 para a aplicação Web principal na porta 5000. Você pode configurar esse número de porta definindo a propriedade PORT do ambiente usando o namespace aws:elasticbeanstalk:application:environment em um arquivo de configuração, conforme mostrado no exemplo a seguir.

option_settings: - namespace: aws:elasticbeanstalk:application:environment option_name: PORT value: <main_port_number>

Para obter mais informações sobre como configurar variáveis de ambiente para o aplicativo, consulte Configurações de opção.

Seu aplicativo deve ter como base a porta que está configurada para ele no proxy. Se você alterar a porta padrão usando a propriedade PORT do ambiente, seu código poderá acessá-la ao ler o valor da variável PORT do ambiente. Por exemplo, chame os.Getenv("PORT") em Go ou System.getenv("PORT") em Java. Se você configurar o proxy para enviar tráfego para vários processos de aplicativo, será possível configurar várias propriedades de ambiente e usar seus valores na configuração de proxy e no código do aplicativo. Outra opção é passar o valor da porta para o processo como um argumento de comando no Procfile. Para obter detalhes sobre isso, expanda a seção Buildfile e Procfile nesta página.

Configurar o nginx

O Elastic Beanstalk usa o nginx como proxy reverso padrão para mapear sua aplicação para o balanceador de carga do Elastic Load Balancing. O Elastic Beanstalk oferece uma configuração de nginx padrão que pode ser estendida ou substituída completamente por sua própria configuração.

nota

Ao adicionar ou editar um arquivo de configuração .conf do nginx, codifique-o como UTF-8.

Para estender a configuração nginx padrão do Elastic Beanstalk, adicione arquivos de configuração .conf a uma pasta denominada .platform/nginx/conf.d/ no pacote de origem da sua aplicação. A configuração nginx do Elastic Beanstalk inclui arquivos .conf nesta pasta automaticamente.

~/workspace/my-app/ |-- .platform | `-- nginx | `-- conf.d | `-- myconf.conf `-- other source files

Para substituir completamente a configuração nginx padrão do Elastic Beanstalk, inclua uma configuração em seu pacote de origem em .platform/nginx/nginx.conf.

~/workspace/my-app/ |-- .platform | `-- nginx | `-- nginx.conf `-- other source files

Se você substituir a configuração nginx do Elastic Beanstalk, adicione a linha a seguir ao seu nginx.conf para extrair as configurações do Elastic Beanstalk para Monitoramento e relatório de integridade aprimorada, mapeamentos automáticos de aplicações e arquivos estáticos.

include conf.d/elasticbeanstalk/*.conf;

Configurar o Apache HTTPD

As plataformas Tomcat, Node.js, PHP e Python permitem escolher o servidor de proxy Apache HTTPD como uma alternativa ao nginx. Esse não é o padrão. O exemplo a seguir configura o Elastic Beanstalk para usar o Apache HTTPD.

exemplo .ebextensions/httpd-proxy.config
option_settings: aws:elasticbeanstalk:environment:proxy: ProxyServer: apache

É possível estender a configuração padrão do Apache do Elastic Beanstalk com seus arquivos de configuração adicionais. Também há opção de substituir completamente a configuração padrão do Apache do Elastic Beanstalk.

Para estender a configuração padrão do Apache do Elastic Beanstalk, adicione arquivos de configuração .conf a uma pasta chamada .platform/httpd/conf.d no pacote de origem da aplicação. A configuração do Apache do Elastic Beanstalk inclui os arquivos .conf nessa pasta automaticamente.

~/workspace/my-app/ |-- .ebextensions | -- httpd-proxy.config |-- .platform | -- httpd | -- conf.d | -- port5000.conf | -- ssl.conf -- index.jsp

Por exemplo, a configuração do Apache 2.4 a seguir adiciona um ouvinte na porta 5000.

exemplo .platform/httpd/conf.d/port5000.conf
listen 5000 <VirtualHost *:5000> <Proxy *> Require all granted </Proxy> ProxyPass / http://localhost:8080/ retry=0 ProxyPassReverse / http://localhost:8080/ ProxyPreserveHost on ErrorLog /var/log/httpd/elasticbeanstalk-error_log </VirtualHost>

Para substituir completamente a configuração padrão do Apache do Elastic Beanstalk, inclua uma configuração no pacote de origem em .platform/httpd/conf/httpd.conf.

~/workspace/my-app/ |-- .ebextensions | -- httpd-proxy.config |-- .platform | `-- httpd | `-- conf | `-- httpd.conf `-- index.jsp
nota

Se você substituir a configuração do Apache do Elastic Beanstalk, adicione as linhas a seguir ao httpd.conf para extrair as configurações do Elastic Beanstalk para Monitoramento e relatório de integridade aprimorada, mapeamentos automáticos de aplicações e arquivos estáticos.

IncludeOptional conf.d/elasticbeanstalk/*.conf
nota

Se você estiver migrando a aplicação do Elastic Beanstalk para uma plataforma Amazon Linux 2 ou Amazon Linux 2023, leia também as informações em Migrar a aplicação Linux do Elastic Beanstalk para o Amazon Linux 2023 ou Amazon Linux 2.

Exemplo de aplicativo com extensões

O exemplo a seguir demonstra um pacote de origem de aplicação com vários recursos de capacidade de extensão compatíveis com as plataformas Amazon Linux 2 e Amazon Linux 2023 do Elastic Beanstalk: um Procfile e arquivos de configuração .ebextensions, hooks personalizados e arquivos de configuração de proxy.

~/my-app/ |-- web.jar |-- Procfile |-- readme.md |-- .ebextensions/ | |-- options.config # Option settings | `-- cloudwatch.config # Other .ebextensions sections, for example files and container commands `-- .platform/ |-- nginx/ # Proxy configuration | |-- nginx.conf | `-- conf.d/ | `-- custom.conf |-- hooks/ # Application deployment hooks | |-- prebuild/ | | |-- 01_set_secrets.sh | | `-- 12_update_permissions.sh | |-- predeploy/ | | `-- 01_some_service_stop.sh | `-- postdeploy/ | |-- 01_set_tmp_file_permissions.sh | |-- 50_run_something_after_app_deployment.sh | `-- 99_some_service_start.sh `-- confighooks/ # Configuration deployment hooks |-- prebuild/ | `-- 01_set_secrets.sh |-- predeploy/ | `-- 01_some_service_stop.sh `-- postdeploy/ |-- 01_run_something_after_config_deployment.sh `-- 99_some_service_start.sh
nota

Algumas dessas extensões não são compatíveis com as versões da plataforma de AMI do Amazon Linux (anteriores ao Amazon Linux 2).

Fluxo de trabalho de implantação da instância

nota

As informações nesta seção não se aplicam à ramificação da plataforma ECS em execução no Amazon Linux 2 e no Amazon Linux 2023. Para obter mais informações, consulte a próxima seção, Fluxo de trabalho de implantação de instâncias para o ECS em execução no Amazon Linux 2 e versões posteriores.

Como existem muitas maneiras de estender a plataforma do ambiente, é útil saber o que acontece sempre que o Elastic Beanstalk provisiona ou implementa uma instância. O diagrama a seguir mostra todo esse fluxo de trabalho de implantação. Ele representa as diferentes fases de uma implantação e as etapas que o Elastic Beanstalk realiza em cada fase.

Observações
  • O diagrama não representa o conjunto completo de etapas que o Elastic Beanstalk realiza em instâncias do ambiente durante a implantação. Nós fornecemos este diagrama como ilustração, para fornecer a você a ordem e o contexto para a execução de suas personalizações.

  • Para simplificar, o diagrama menciona apenas os subdiretórios de hook .platform/hooks/* (para implantações de aplicações), e não os subdiretórios de hook .platform/confighooks/* (para implantações de configurações). Os hooks nos últimos subdiretórios são executados durante exatamente as mesmas etapas que os hooks nos subdiretórios correspondentes mostrados no diagrama.


        Ordem de execução de extensões em uma instância em um ambiente usando uma versão de plataforma Amazon Linux 2

A lista a seguir detalha as fases e etapas de implantação.

  1. Passos iniciais

    O Elastic Beanstalk baixa e extrai a aplicação. Após cada uma dessas etapas, o Elastic Beanstalk executa uma das etapas de extensibilidade.

    1. Executa comandos encontrados na seção commands: de qualquer arquivo de configuração.

    2. Executa todos os arquivos executáveis encontrados no diretório .platform/hooks/prebuild do pacote de origem (.platform/confighooks/prebuild para uma implantação de configuração).

  2. Configure

    O Elastic Beanstalk configura a aplicação e o servidor de proxy.

    1. Executa os comandos encontrados no Buildfile no pacote de origem.

    2. Copia seus arquivos de configuração de proxy personalizados, se você tiver algum no diretório .platform/nginx do pacote de origem, para seu local de runtime.

    3. Executa comandos encontrados na seção container_commands: de qualquer arquivo de configuração.

    4. Executa todos os arquivos executáveis encontrados no diretório .platform/hooks/predeploy do pacote de origem (.platform/confighooks/predeploy para uma implantação de configuração).

  3. Implante

    O Elastic Beanstalk implanta e executa a aplicação e o servidor de proxy.

    1. Executa o comando encontrado no arquivo Procfile em seu pacote de origem.

    2. Executa ou executa novamente o servidor de proxy com seus arquivos de configuração de proxy personalizados, se você tiver algum.

    3. Executa todos os arquivos executáveis encontrados no diretório .platform/hooks/postdeploy do pacote de origem (.platform/confighooks/postdeploy para uma implantação de configuração).

Fluxo de trabalho de implantação de instâncias para o ECS em execução no Amazon Linux 2 e versões posteriores

A seção anterior descreve os recursos de extensibilidade compatíveis ao longo das fases do fluxo de trabalho de implantação da aplicação. Há algumas diferenças para ramificação da plataforma Docker no ECS em execução no Amazon Linux 2 e versões posteriores. Esta seção explica como esses conceitos se aplicam a essa ramificação específica da plataforma.

Como existem muitas maneiras de estender a plataforma do ambiente, é útil saber o que acontece sempre que o Elastic Beanstalk provisiona ou implementa uma instância. O diagrama a seguir mostra todo esse fluxo de trabalho de implantação para um ambiente baseado nas ramificações de plataforma ECS em execução no Amazon Linux 2 e ECS em execução no Amazon Linux 2023. Ele representa as diferentes fases de uma implantação e as etapas que o Elastic Beanstalk realiza em cada fase.

Ao contrário do fluxo de trabalho descrito na seção anterior, a fase de configuração da implantação não é compatível com os seguintes recursos de extensibilidade: comandos Buildfile, comandos Procfile, configuração de proxy reverso.

Observações
  • O diagrama não representa o conjunto completo de etapas que o Elastic Beanstalk realiza em instâncias do ambiente durante a implantação. Nós fornecemos este diagrama como ilustração, para fornecer a você a ordem e o contexto para a execução de suas personalizações.

  • Para simplificar, o diagrama menciona apenas os subdiretórios de hook .platform/hooks/* (para implantações de aplicações), e não os subdiretórios de hook .platform/confighooks/* (para implantações de configurações). Os hooks nos últimos subdiretórios são executados durante exatamente as mesmas etapas que os hooks nos subdiretórios correspondentes mostrados no diagrama.


        Ordem de execução das extensões em uma instância em um ambiente para a ramificação da plataforma ECS em execução no Amazon Linux 2 ou versões posteriores

A lista a seguir detalha as etapas do fluxo de trabalho de implantação.

  1. Executa todos os arquivos executáveis encontrados no diretório appdeploy/pre em EBhooksDir.

  2. Executa todos os arquivos executáveis encontrados no diretório .platform/hooks/prebuild do pacote de origem (.platform/confighooks/prebuild para uma implantação de configuração).

  3. Executa todos os arquivos executáveis encontrados no diretório .platform/hooks/predeploy do pacote de origem (.platform/confighooks/predeploy para uma implantação de configuração).

  4. Executa todos os arquivos executáveis encontrados no diretório appdeploy/enact em EBhooksDir.

  5. Executa todos os arquivos executáveis encontrados no diretório appdeploy/post em EBhooksDir.

  6. Executa todos os arquivos executáveis encontrados no diretório .platform/hooks/postdeploy do pacote de origem (.platform/confighooks/postdeploy para uma implantação de configuração).

A referência a EBhooksDir representa o caminho do diretório de hooks da plataforma. Para recuperar o nome do caminho do diretório, use a ferramenta de script get-config na linha de comando da instância do ambiente, como mostrado:

$ /opt/elasticbeanstalk/bin/get-config platformconfig -k EBhooksDir