Acessar a interface de linha de comando do Airflow

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

O Apache Airflow tem uma interface de linha de comando (CLI) que pode ser usada para realizar tarefas, como acionar e gerenciar DAGs, receber informações sobre execuções e tarefas do DAG, adicionar e excluir conexões e usuários.

Comandos compatíveis da CLI do Airflow

O Airflow usa a sintaxe da CLI do Airflow, que é descrita na documentação do Airflow.

O Cloud Composer 3 é compatível com os seguintes comandos da CLI do Airflow:

  • (Airflow 2 e 3) O comando gcloud composer environments run executa comandos da CLI do Airflow para seu ambiente. Alguns comandos são bloqueados e não podem ser executados. Consulte a referência do comando para conferir a lista de comandos compatíveis da CLI do Airflow.

  • (Airflow 3) A ferramenta de linha de comando airflowctl oferece suporte a um subconjunto de comandos da CLI do Airflow e os executa usando a API REST do Airflow. Todos os comandos disponíveis em airflowctl são compatíveis com o Cloud Composer. Verifique se a conta do Airflow do usuário tem uma função do Airflow que pode executar um comando específico.

Antes de começar

Para executar comandos da CLI do Airflow pela Google Cloud CLI:

  • Sua Conta do Google precisa ter permissões para usar a Google Cloud CLI com o Cloud Composer e executar comandos da CLI do Airflow.

  • Os comandos da CLI do Airflow executados pela Google Cloud CLI consomem a cota de environments.executeAirflowCommand.

Para executar comandos da CLI do Airflow usando a ferramenta de linha de comando airflowctl (no Airflow 3):

Executar comandos da CLI do Airflow com a CLI gcloud

Para executar comandos da CLI do Airflow nos seus ambientes, use a CLI gcloud:

gcloud composer environments run ENVIRONMENT_NAME \
    --location LOCATION \
    SUBCOMMAND \
    -- SUBCOMMAND_ARGUMENTS

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.
  • SUBCOMMAND: um dos comandos compatíveis da CLI do Airflow.
  • SUBCOMMAND_ARGUMENTS com argumentos para o comando da CLI do Airflow.

Separador de argumentos de subcomando

Separe os argumentos do comando da CLI do Airflow especificado com --:

  • Especifique comandos CLI compostos como um subcomando.
  • Especifique qualquer argumento para comandos compostos como argumentos de subcomando, após um separador --.

Exemplo:

gcloud composer environments run example-environment \
    dags list -- --output=json

Local padrão

A maioria dos comandos gcloud composer requer um local. Especifique o local com a sinalização --location ou definindo o local padrão.

Por exemplo, para acionar um DAG chamado sample_quickstart com o ID 5077 no seu ambiente do Cloud Composer:

gcloud composer environments run example-environment \
    --location us-central1 dags trigger -- sample_quickstart \
    --run-id=5077

Executar comandos da CLI do Airflow com o airflowctl

A ferramenta de linha de comando airflowctl é um utilitário de linha de comando fornecido pelo Airflow para executar comandos da CLI do Airflow. Ele oferece suporte a um subconjunto de comandos da CLI do Airflow e os executa usando API REST do Airflow. Todos os comandos disponíveis em airflowctl são compatíveis com o Cloud Composer.

A autorização e a autenticação com airflowctl no Cloud Composer funcionam da seguinte maneira:

  • Como o airflowctl usa a API REST do Airflow, verifique se a conta de usuário do Airflow associada à sua Conta do Google ou conta de serviço tem uma função do Airflow com permissões suficientes para executar um comando. Por exemplo, alguns comandos só podem ser executados por usuários do Airflow com a função Admin.

  • O token de API usado pelo airflowctl é fornecido com o comando gcloud auth. Por padrão, o token tem um período de expiração de 1 hora. É possível mudar isso com o argumento --lifetime fornecido a esse comando.

Para autenticar com airflowctl, execute o seguinte comando:

airflowctl auth login \
  --api-url WEB_SERVER_URL \
  --api-token $(gcloud auth print-access-token)

Substitua:

Exemplo:

airflowctl auth login \
  --api-url https://example-dot-us-central1.composer.googleusercontent.com \
  --api-token $(gcloud auth print-access-token)

Depois de se autenticar com airflowctl, é possível executar comandos da CLI do Airflow:

airflowctl dags list

Executar comandos da CLI do Airflow pela API do Cloud Composer

No Cloud Composer 3, é possível executar comandos da CLI do Airflow pela API Cloud Composer.

Executar um comando

Crie uma solicitação de API environments.executeAirflowCommand:

{
  "environment": "projects/PROJECT_ID/locations/LOCATION/environments/ENVIRONMENT_NAME",
  "command": "AIRFLOW_COMMAND",
  "subcommand": "AIRFLOW_SUBCOMMAND",
  "parameters": [
    "SUBCOMMAND_PARAMETER"
  ]
}

Substitua:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região em que o ambiente está localizado.
  • ENVIRONMENT_NAME: o nome do ambiente;
  • AIRFLOW_COMMAND: comando da CLI do Airflow que você quer executar, como dags.
  • AIRFLOW_SUBCOMMAND: subcomando do comando da CLI do Airflow que você quer executar, como list.
  • (opcional) SUBCOMMAND_PARAMETER: parâmetros para o subcomando. Se você quiser usar mais de um parâmetro, adicione mais itens à lista.

Exemplo:

// POST https://composer.googleapis.com/v1/{environment=projects/*/locations/*/environments/*}:executeAirflowCommand
{
  "environment": "projects/example-project/locations/us-central1/environments/example-environment",
  "command": "dags",
  "subcommand": "list",
  "parameters": [
    "-o json",
    "--verbose"
  ]
}

Verificar o status do comando

Depois de executar um comando da CLI do Airflow pela API Cloud Composer, verifique se o comando foi concluído com sucesso fazendo uma solicitação PollAirflowCommand e inspecionando os campos em exitInfo para erros e códigos de status. O campo output contém linhas de registro.

Para receber o status de execução do comando e buscar registros, forneça os valores executionId, pod e podNamespace retornados por ExecuteAirflowCommandRequest:

Exemplo:

// POST https://composer.googleapis.com/v1/{environment=projects/*/locations/*/environments/*}:pollAirflowCommand
{
  "executionId": "a117da94-355d-4ad4-839e-ac39ccb0bf48",
  "pod": "airflow-webserver-66d96b858f-tn96b",
  "podNamespace": "airflow-2-10-2-build-13-226523e4",
  "nextLineNumber": 1
}

A seguir