Como usar um script de startup com o Amazon MWAA - Amazon Managed Workflows for Apache Airflow
Configurar um script de startupInstale os runtimes do LinuxDefinição de variáveis de ambiente

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

Como usar um script de startup com o Amazon MWAA

Um script de startup é um script de shell (.sh) que você hospeda no bucket do Amazon S3 do seu ambiente, semelhante aos seus DAGs, requisitos e plug-ins. O Amazon MWAA executa esse script durante o startup em cada componente individual do Apache Airflow (operador, programador e servidor web) antes de instalar os requisitos e inicializar o processo do Apache Airflow. Use um script de startup para:

  • Instalar os runtimes: instale runtimes do Linux exigidos por seus fluxos de trabalho e conexões.

  • Configurar variáveis de ambiente: defina variáveis de ambiente para cada componente do Apache Airflow. Substitua variáveis comuns como PATH, PYTHONPATH e LD_LIBRARY_PATH.

  • Gerencie chaves e tokens: transmita tokens de acesso para repositórios personalizados para requirements.txt e configure chaves de segurança.

Os tópicos a seguir descrevem como configurar um script de startup para instalar runtimes do Linux, definir variáveis de ambiente e solucionar problemas relacionados usando o CloudWatch Logs.

Configurar um script de startup

Para usar um script de startup com seu ambiente Amazon MWAA existente, faça upload de um arquivo .sh para o bucket Amazon S3 do seu ambiente. Em seguida, para associar o script ao ambiente, especifique o seguinte nos detalhes do seu ambiente:

  • O caminho do URL do Amazon S3 para o script: o caminho relativo para o script hospedado em seu bucket, por exemplo, s3://mwaa-environment/startup.sh

  • O ID da versão do Amazon S3 do script: a versão do script de startup de shell em seu bucket do Amazon S3. Você deve especificar o ID da versão que o Amazon S3 atribui ao arquivo toda vez que você atualiza o script. Os IDs de versão são strings opacas Unicode, com codificação UTF-8 e prontas para URL que não têm mais de 1.024 bytes de comprimento, por exemplo 3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo.

Para concluir as etapas desta seção, use o seguinte exemplo de script. O script gera o valor atribuído a MWAA_AIRFLOW_COMPONENT. Essa variável de ambiente identifica cada componente do Apache Airflow no qual o script é executado.

Copie o código e salve-o localmente como startup.sh. 

#!/bin/sh
​
echo "Printing Apache Airflow component"
echo $MWAA_AIRFLOW_COMPONENT

Em seguida, faça upload do script para o seu bucket do Amazon S3.

AWS Management Console
Para fazer o upload um script de shell (console)

  1. Faça login no AWS Management Console e abra o console do Amazon S3 em https://console.aws.amazon.com/s3/.

  2. Na lista Buckets, escolha o nome do bucket associado ao ambiente.

  3. Na guia Objects (Objetos), escolha Upload (Fazer upload).

  4. Na página Upload, arraste e solte o script de shell que você criou.

  5. Escolha Upload (Carregar).

O script aparece na lista de objetos. O Amazon S3 cria um novo ID de versão do arquivo. Se você atualizar o script e fizer o upload novamente usando o mesmo nome de arquivo, uma nova ID de versão será atribuída ao arquivo.

AWS CLI
Para criar e fazer o upload um script de shell (CLI)

  1. Abra um novo prompt de comando e execute o comando ls do Amazon S3 para listar e identificar o bucket associado ao seu ambiente. 

    $ aws s3 ls

  2. Navegue até a pasta em que você salvou o script de shell. Use cp em uma nova janela de prompt para fazer o upload do script em seu bucket. Substitua your-s3-bucket por suas informações. 

    $ aws s3 cp startup.sh s3://your-s3-bucket/startup.sh

    Se tiver êxito, o Amazon S3 envia o caminho da URL para o objeto:

    upload: ./startup.sh to s3://your-s3-bucket/startup.sh

  3. Use o comando a seguir para recuperar o ID da versão mais recente do script. 

    $ aws s3api list-object-versions --bucket your-s3-bucket --prefix startup --query 'Versions[?IsLatest].[VersionId]' --output text
    BbdVMmBRjtestta1EsVnbybZp1Wqh1J4

Você especifica esse ID de versão ao associar o script a um ambiente.

Agora, associe o script ao seu ambiente.

AWS Management Console
Para associar o script a um ambiente (console)

  1. Abra a página Ambientes no console do Amazon MWAA.

  2. Selecione a linha do ambiente que você deseja atualizar e escolha Editar.

  3. Na página Especificar detalhes, em Arquivo de script de inicialização - opcional, insira a URL do Amazon S3 para o script, por exemplo:. s3://your-mwaa-bucket/startup-sh.

  4. Escolha a versão mais recente na lista suspensa ou navegue por S3 para encontrar o script.

  5. Escolha Avançar para abrir a página Revisar e salvar.

  6. Revise as alterações e escolha Salvar.

As atualizações do ambiente podem levar de 10 a 30 minutos. O Amazon MWAA executa o script de startup à medida que cada componente do seu ambiente é reiniciado.

AWS CLI
Para associar o script a um ambiente (CLI)

  • Abra um prompt de comando e use update-environment para especificar a URL e o ID da versão do Amazon S3 para o script. 

    $ aws mwaa update-environment \
    --name your-mwaa-environment \
    --startup-script-s3-path startup.sh \
    --startup-script-s3-object-version BbdVMmBRjtestta1EsVnbybZp1Wqh1J4

    Se for bem-sucedido, o Amazon MWAA retornará o nome do recurso da Amazon (ARN) do ambiente:

    arn:aws::airflow:us-west-2:123456789012:environment/your-mwaa-environment

A atualização do ambiente pode levar de 10 a 30 minutos. O Amazon MWAA executa o script de startup à medida que cada componente do seu ambiente é reiniciado.

Por fim, recupere os eventos de log para verificar se o script está funcionando conforme o esperado. Quando você ativa o registro em log para cada componente do Apache Airflow, o Amazon MWAA cria um novo grupo de logs e um novo fluxo de logs. Para obter mais informações, consulte Tipos de logs do Apache Airflow.

AWS Management Console
Para verificar o fluxo de logs do Apache Airflow (console)

  1. Abra a página Ambientes no console do Amazon MWAA.

  2. Escolha seu ambiente.

  3. No painel Monitoramento, escolha o grupo de logs para o qual você deseja visualizar os logs, por exemplo, grupo de logs do programador do Airflow.

  4. No console do CloudWatch, na lista fluxo de logs, escolha um fluxo com o seguinte prefixo: startup_script_exection_ip.

  5. No painel Eventos de logs, você verá a saída do comando imprimindo o valor de MWAA_AIRFLOW_COMPONENT. Por exemplo, para logs do programador, você fará o seguinte: 

    Printing Apache Airflow component
scheduler
Finished running startup script. Execution time: 0.004s.
Running verification
Verification completed

Você pode repetir as etapas anteriores para visualizar os logs do operador e do servidor web.

Instale os runtimes do Linux usando um script de startup

Use um script de startup para atualizar o sistema operacional de um componente do Apache Airflow e instale bibliotecas de runtime adicionais para usar com seus fluxos de trabalho. Por exemplo, o script a seguir executa yum update para atualizar o sistema operacional.

Ao executar yum update em um script de startup, você deve excluir o Python usando --exclude=python*, conforme mostrado no exemplo. Para que seu ambiente seja executado, o Amazon MWAA instala uma versão específica do Python compatível com seu ambiente. Portanto, não é possível atualizar a versão do Python do ambiente usando um script de startup. 

#!/bin/sh

echo "Updating operating system"
sudo yum update -y --exclude=python*

Para instalar runtimes em um componente específico do Apache Airflow, use instruções condicionais MWAA_AIRFLOW_COMPONENT, if e fi. Este exemplo executa um único comando para instalar a biblioteca libaio no programador e no operador, mas não no servidor web.

Importante

  • Se você configurou um servidor web privado, deve usar a condição a seguir ou fornecer todos os arquivos de instalação localmente para evitar atingir os tempos limite da instalação.

  • Use sudo para executar operações que exigem privilégios administrativos. 

#!/bin/sh

if [[ "${MWAA_AIRFLOW_COMPONENT}" != "webserver" ]]
then
     sudo yum -y install libaio
fi

Você pode usar um script de startup para verificar a versão do Python. 

#!/bin/sh

export PYTHON_VERSION_CHECK=`python -c 'import sys; version=sys.version_info[:3]; print("{0}.{1}.{2}".format(*version))'`
echo "Python version is $PYTHON_VERSION_CHECK"

O Amazon MWAA não oferece suporta à substituição da versão padrão do Python, pois isso pode levar a incompatibilidades com as bibliotecas instaladas do Apache Airflow.

Definir variáveis de ambiente usando um script de startup

Use scripts de startup para definir variáveis de ambiente e modificar as configurações do Apache Airflow. O exemplo a seguir define uma nova variável, ENVIRONMENT_STAGE. Você pode referenciar essa variável em um DAG ou em seus módulos personalizados. 

#!/bin/sh

export ENVIRONMENT_STAGE="development"
echo "$ENVIRONMENT_STAGE"

Use scripts de startup para sobrescrever variáveis comuns do Apache Airflow ou do sistema. Por exemplo, você configura LD_LIBRARY_PATH para instruir o Python a procurar binários no caminho especificado. Isso permite que você forneça binários personalizados para seus fluxos de trabalho usando plug-ins: 

#!/bin/sh

export LD_LIBRARY_PATH=/usr/local/airflow/plugins/your-custom-binary

Variáveis de ambiente reservadas

O Amazon MWAA reserva um conjunto de importantes variáveis de ambientes. Se você sobrescrever uma variável reservada, o Amazon MWAA a restaurará ao padrão. A seguir, listamos as variáveis reservadas:

  • MWAA__AIRFLOW__COMPONENT: usada para identificar o componente Apache Airflow com um dos seguintes valores: scheduler, worker ou webserver.

  • AIRFLOW__WEBSERVER__SECRET_KEY: a chave secreta usada para assinar com segurança os cookies de sessão no servidor web Apache Airflow.

  • AIRFLOW__CORE__FERNET_KEY: a chave usada para criptografia e decodificação de dados confidenciais armazenados no banco de dados de metadados, por exemplo, senhas de conexão.

  • AIRFLOW_HOME: o caminho para o diretório inicial do Apache Airflow, onde os arquivos de configuração e os arquivos DAG são armazenados localmente.

  • AIRFLOW__CELERY__BROKER_URL: a URL do agente de mensagens usada para comunicação entre o agendador do Apache Airflow e os nó de processamento do Celery.

  • AIRFLOW__CELERY__RESULT_BACKEND: a URL do banco de dados usada para armazenar os resultados das tarefas do Celery.

  • AIRFLOW__CORE__EXECUTOR: a classe executora que o Apache Airflow deve usar. No Amazon MWAA, isso é um CeleryExecutor

  • AIRFLOW__CORE__LOAD_EXAMPLES: usada para ativar ou desativar o carregamento de exemplos de DAGs.

  • AIRFLOW__METRICS__METRICS_BLOCK_LIST: usada para gerenciar quais métricas do Apache Airflow são emitidas e capturadas pelo Amazon MWAA no CloudWatch.

  • SQL_ALCHEMY_CONN: a string de conexão do banco de dados RDS for PostgreSQL usada para armazenar metadados do Apache Airflow no Amazon MWAA.

  • AIRFLOW__CORE__SQL_ALCHEMY_CONN: usada para a mesma finalidade de SQL_ALCHEMY_CONN, mas seguindo a nova convenção de nomenclatura do Apache Airflow.

  • AIRFLOW__CELERY__DEFAULT_QUEUE: a fila padrão para tarefas do Celery no Apache Airflow.

  • AIRFLOW__OPERATORS__DEFAULT_QUEUE: a fila padrão para tarefas usando operadores específicos do Apache Airflow.

  • AIRFLOW_VERSION: a versão Apache Airflow instalada no ambiente Amazon MWAA.

  • AIRFLOW_CONN_AWS_DEFAULT: as credenciais AWS padrão usadas para integração com outros serviços da AWS.

  • AWS_DEFAULT_REGION: define a Região padrão AWS usada com as credenciais padrão para integração com outros serviços na AWS.

  • AWS_REGION: se definida, essa variável de ambiente substituirá os valores na variável de ambiente AWS_DEFAULT_REGION e na região da configuração de perfil.

  • PYTHONUNBUFFERED: usada para enviar os fluxos stdout e stderr para logs de contêiner.

  • AIRFLOW__METRICS__STATSD_ALLOW_LIST: usada para configurar uma lista de permissões de prefixos separados por vírgula para enviar as métricas que começam com os elementos da lista.

  • AIRFLOW__METRICS__STATSD_ON: ativa o envio de métricas para StatsD.

  • AIRFLOW__METRICS__STATSD_HOST: usada para se conectar ao daemon StatSD.

  • AIRFLOW__METRICS__STATSD_PORT: usada para se conectar ao daemon StatSD.

  • AIRFLOW__METRICS__STATSD_PREFIX: usada para se conectar ao daemon StatSD.

  • AIRFLOW__CELERY__WORKER_AUTOSCALE: define a simultaneidade máxima e mínima.

  • AIRFLOW__CORE__DAG_CONCURRENCY: define o número de instâncias de tarefas que podem ser executadas simultaneamente pelo programador em um DAG.

  • AIRFLOW__CORE__MAX_ACTIVE_TASKS_PER_DAG: define o número máximo de tarefas ativas por DAG.

  • AIRFLOW__CORE__PARALLELISM: define o número máximo de instâncias de tarefas que podem ser executadas simultaneamente.

  • AIRFLOW__SCHEDULER__PARSING_PROCESSES: define o número máximo de processos analisados pelo programador para agendar DAGs.

  • AIRFLOW__CELERY_BROKER_TRANSPORT_OPTIONS__VISIBILITY_TIMEOUT: define o número de segundos que um operador espera para reconhecer a tarefa antes que a mensagem seja reenviada a outro operador.

  • AIRFLOW__CELERY_BROKER_TRANSPORT_OPTIONS__REGION: define a Região AWS para o transporte subjacente Celery.

  • AIRFLOW__CELERY_BROKER_TRANSPORT_OPTIONS__PREDEFINED_QUEUES: define a fila para o transporte subjacente do Celery.

  • AIRFLOW_SCHEDULER_ALLOWED_RUN_ID_PATTERN: usado para verificar a validade de sua entrada para o parâmetro run_id ao acionar um DAG.

  • AIRFLOW__WEBSERVER__BASE_URL: a URL do servidor web usada para fazer o host da IU do Apache Airflow.

Variáveis de ambiente não reservadas

Você pode usar um script de startup para substituir variáveis de ambiente não reservadas. A lista a seguir fornece algumas dessas variáveis comuns:

  • PATH: especifica uma lista de diretórios em que o sistema operacional pesquisa arquivos e scripts executáveis. Quando um comando é executado na linha de comando, o sistema verifica os diretórios em PATH para encontrar e executar o comando. Ao criar operadores ou tarefas personalizadas no Apache Airflow, talvez seja necessário confiar em scripts ou executáveis externos. Se os diretórios que contêm esses arquivos não estiverem no especificado na variável PATH, as tarefas não serão executadas quando o sistema não conseguir localizá-las. Ao adicionar os diretórios apropriados para PATH, as tarefas do Apache Airflow podem encontrar e executar os executáveis necessários.

  • PYTHONPATH: usado pelo interpretador do Python para determinar quais diretórios pesquisar módulos e pacotes importados. É uma lista de diretórios que você pode adicionar ao caminho de pesquisa padrão. Isso permite que o interpretador encontre e carregue bibliotecas Python não incluídas na biblioteca padrão ou instaladas nos diretórios do sistema. Use essa variável para adicionar seus módulos e pacotes Python personalizados e usá-los com seus DAGs.

  • LD_LIBRARY_PATH: uma variável de ambiente usada pelo vinculador dinâmico e pelo carregador no Linux para encontrar e carregar bibliotecas compartilhadas. Especifica uma lista de diretórios contendo bibliotecas compartilhadas, que são pesquisadas antes dos diretórios padrão da biblioteca do sistema. Use essa variável para especificar seus binários personalizados.

  • CLASSPATH: usada pelo Ambiente de Execução Java (JRE) e pelo Java Development Kit (JDK) para localizar e carregar classes, bibliotecas e recursos Java em runtime. É uma lista de diretórios, arquivos JAR e arquivos ZIP que contêm código Java compilado.