Acessar a interface de linha de comando do Airflow

Airflow Gerenciado (Geração 3) | Airflow Gerenciado (Geração 2) | Airflow Gerenciado (Geração 1 legada)

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 Airflow Gerenciado (Geração 3) oferece suporte aos 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 airflowctl ferramenta de linha de comando 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 no airflowctl são compatíveis com o Airflow Gerenciado. Verifique se a conta do Airflow do usuário tem um papel 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 Airflow Gerenciado e executar comandos da CLI do Airflow.

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

Para executar comandos da CLI do Airflow pela airflowctl ferramenta de linha de comando (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 --location sinalização ou definindo o local padrão.

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

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

Executar comandos da CLI do Airflow com 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. Ela 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 no airflowctl são compatíveis com o Airflow Gerenciado.

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

  • Como 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 um papel do Airflow com permissões suficientes para executar um comando. Por exemplo, alguns comandos só podem ser executados por usuários do Airflow que têm o papel Admin.

  • O token de API usado pelo airflowctl é fornecido com o gcloud auth application-default print-access-token comando. Por padrão, o token tem um período de validade 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 application-default print-access-token)

Substitua:

Exemplo:

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

Depois de autenticar com airflowctl, você pode executar comandos da CLI do Airflow:

airflowctl dags list

Executar comandos da CLI do Airflow pela API Cloud Composer

No Airflow Gerenciado (Geração 3), é possível executar comandos da CLI do Airflow pela API 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 do 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 fazendo uma PollAirflowCommand solicitação 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