Acceder a la interfaz de línea de comandos de Airflow

Airflow administrado (3ª gen.) | Airflow administrado (2ª gen.) | Airflow administrado (1ª gen. heredada)

Apache Airflow tiene una interfaz de línea de comandos (CLI) que puedes usar para realizar tareas como activar y administrar DAG, obtener información sobre las ejecuciones y tareas de DAG, agregar y borrar conexiones y usuarios.

Comandos compatibles con la CLI de Airflow

Airflow usa la sintaxis de la CLI de Airflow, que se describe en la documentación de Airflow.

Airflow administrado (3ª gen.) admite los siguientes comandos de la CLI de Airflow:

  • (Airflow 2 y 3) El comando gcloud composer environments run ejecuta comandos de la CLI de Airflow para tu entorno. Algunos comandos están bloqueados y no es posible ejecutarlos. Consulta la referencia del comando para obtener la lista de comandos de la CLI de Airflow admitidos.

  • (Airflow 3) La airflowctl herramienta de línea de comandos admite un subconjunto de comandos de la CLI de Airflow y los ejecuta con la API de REST de Airflow. Todos los comandos disponibles en airflowctl son compatibles con Airflow administrado. Asegúrate de que la cuenta de Airflow del usuario tenga un rol de Airflow que pueda ejecutar un comando específico.

Antes de comenzar

Para ejecutar comandos de la CLI de Airflow a través de Google Cloud CLI, haz lo siguiente:

  • Tu Cuenta de Google debe tener permisos para usar Google Cloud CLI con Airflow administrado y ejecutar comandos de la CLI de Airflow.

  • Los comandos de la CLI de Airflow que se ejecutan a través de Google Cloud CLI consumen la environments.executeAirflowCommand cuota.

Para ejecutar comandos de la CLI de Airflow a través de la airflowctl herramienta de línea de comandos (en Airflow 3), haz lo siguiente:

Ejecuta comandos de la CLI de Airflow con gcloud CLI

Para ejecutar comandos de la CLI de Airflow en tus entornos, usa gcloud CLI:

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

Reemplaza lo siguiente:

  • ENVIRONMENT_NAME: Es el nombre de tu entorno.
  • LOCATION: Es la región en la que se encuentra el entorno.
  • SUBCOMMAND: uno de los comandos de la CLI de Airflow admitidos.
  • SUBCOMMAND_ARGUMENTS por argumentos para el comando de la CLI de Airflow

Separador de argumentos del subcomando

Separa los argumentos para el comando de la CLI de Airflow especificado con --:

  • Especifica los comandos compuestos de la CLI como subcomando.
  • Especifica los argumentos para los comandos compuestos como argumentos de subcomandos, después de un separador --.

Ejemplo:

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

Ubicación predeterminada

La mayoría de los comandos gcloud composer requiere una ubicación. Puedes especificar la ubicación con la marca --location o si configuras la ubicación predeterminada.

Por ejemplo, para activar un DAG con el nombre sample_quickstart y el ID 5077 en tu entorno de Airflow administrado, ejecuta lo siguiente:

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

Ejecuta comandos de la CLI de Airflow con airflowctl

La herramienta de línea de comandos airflowctl es una utilidad de línea de comandos que proporciona Airflow para ejecutar comandos de la CLI de Airflow. Admite un subconjunto de comandos de la CLI de Airflow y los ejecuta con la API de REST de Airflow. Todos los comandos disponibles en airflowctl son compatibles con Airflow administrado.

La autorización y la autenticación con airflowctl en Airflow administrado funcionan de la siguiente manera:

  • Debido a que airflowctl usa la API de REST de Airflow, asegúrate de que la cuenta de usuario de Airflow asociada con tu Cuenta de Google o cuenta de servicio tenga un rol de Airflow con los permisos suficientes para ejecutar un comando. Por ejemplo, algunos comandos solo pueden ser ejecutados por usuarios de Airflow que tienen el rol Admin.

  • El token de API que usa airflowctl se proporciona con el gcloud auth application-default print-access-token comando. De forma predeterminada, el token tiene un período de vencimiento de 1 hora. Puedes cambiarlo con el argumento --lifetime que se proporciona a este comando.

Para autenticarte con airflowctl, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

Ejemplo:

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

Después de autenticarte con airflowctl, puedes ejecutar comandos de la CLI de Airflow:

airflowctl dags list

Ejecuta comandos de la CLI de Airflow a través de la API de Composer

En Managed Airflow (3ª gen.), puedes ejecutar comandos de la CLI de Airflow a través de la API de Composer.

Ejecutar un comando

Construye una solicitud a la API de environments.executeAirflowCommand:

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

Reemplaza lo siguiente:

  • PROJECT_ID: el ID del proyecto.
  • LOCATION: Es la región en la que se encuentra el entorno.
  • ENVIRONMENT_NAME: Es el nombre de tu entorno.
  • AIRFLOW_COMMAND: Es el comando de la CLI de Airflow que deseas ejecutar, como dags.
  • AIRFLOW_SUBCOMMAND: Es el subcomando para el comando de la CLI de Airflow que deseas ejecutar, como list.
  • (opcional) SUBCOMMAND_PARAMETER: Son los parámetros del subcomando. Si deseas usar más de un parámetro, agrega más elementos a la lista.

Ejemplo:

// 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"
  ]
}

Consultar el estado del comando

Después de ejecutar un comando de la CLI de Airflow a través de la API de Cloud Composer, verifica si el comando se completó correctamente. Para ello, realiza una solicitud a PollAirflowCommand y examina los campos en exitInfo para ver los errores y los códigos de estado. El campo output contiene líneas de registro.

Para obtener el estado de ejecución del comando y recuperar los registros, proporciona los valores executionId, pod y podNamespace que muestra ExecuteAirflowCommandRequest:

Ejemplo:

// 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
}

¿Qué sigue?