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

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Apache Airflow tiene una interfaz de línea de comandos (CLI) que puedes usar para realizar tareas como activar y gestionar DAGs, obtener información sobre ejecuciones de DAGs y tareas, y añadir y eliminar conexiones y usuarios.

Comandos de la CLI de Airflow admitidos

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

Cloud Composer 3 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 se pueden ejecutar. Consulta la referencia del comando para ver la lista de comandos de la CLI de Airflow compatibles.

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

Antes de empezar

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

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

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

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

Ejecutar comandos de la CLI de Airflow con la CLI de gcloud

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

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

Haz los cambios siguientes:

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

Separador de argumentos de subcomando

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

  • Especifica comandos compuestos de la CLI como subcomandos.
  • Especifica los argumentos de los comandos compuestos como argumentos de subcomando, 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 de gcloud composer requieren una ubicación. Puedes especificar la ubicación con la marca --location o configurar la ubicación predeterminada.

Por ejemplo, para activar un DAG llamado sample_quickstart con el ID 5077 en tu entorno de Cloud Composer, haz lo siguiente:

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

Ejecutar comandos de la CLI de Airflow con airflowctl

La airflowctl herramienta de línea de comandos 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 mediante la API REST de Airflow. Todos los comandos disponibles en airflowctl se admiten en Cloud Composer.

La autorización y la autenticación con airflowctl en Cloud Composer funcionan de la siguiente manera:

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

  • El token de API que usa airflowctl se proporciona con el comando gcloud auth. De forma predeterminada, el token tiene un periodo de caducidad de 1 hora. Puedes cambiarlo con el argumento --lifetime proporcionado a este comando.

Para autenticarte con airflowctl, ejecuta el siguiente comando:

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

Haz los cambios siguientes:

Ejemplo:

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

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

airflowctl dags list

Ejecutar comandos de la CLI de Airflow a través de la API de Cloud Composer

En Cloud Composer 3, puedes ejecutar comandos de la CLI de Airflow a través de la API de Cloud Composer.

Ejecutar un comando

Crea una solicitud de API environments.executeAirflowCommand:

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

Haz los cambios siguientes:

  • PROJECT_ID: el ID de proyecto.
  • LOCATION: la región en la que se encuentra el entorno.
  • ENVIRONMENT_NAME: el nombre de tu entorno.
  • AIRFLOW_COMMAND: comando de la CLI de Airflow que quieres ejecutar, como dags.
  • AIRFLOW_SUBCOMMAND: subcomando del comando de la CLI de Airflow que quieras ejecutar, como list.
  • (Opcional) SUBCOMMAND_PARAMETER: parámetros del subcomando. Si quieres usar más de un parámetro, añade 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"
  ]
}

Estado del comando de sondeo

Después de ejecutar un comando de la CLI de Airflow a través de la API de Cloud Composer, comprueba si el comando se ha completado correctamente haciendo una solicitud PollAirflowCommand e inspeccionando los campos de exitInfo para ver si hay errores y códigos de estado. El campo output contiene líneas de registro.

Para obtener el estado de ejecución del comando y los registros, proporcione los valores executionId, pod y podNamespace devueltos por 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
}

Siguientes pasos