Ejecuta un entorno de Airflow local con la herramienta de CLI de desarrollo local de Composer

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

En esta sección, se describe cómo crear, configurar y ejecutar un entorno de Airflow local con la herramienta de la CLI de desarrollo local de Composer.

Acerca de la herramienta de la CLI de desarrollo local de Composer

La herramienta de la CLI de desarrollo local de Composer optimiza el desarrollo de DAG de Apache Airflow para Airflow administrado mediante la ejecución de un entorno de Airflow de forma local. Este entorno de Airflow local usa una imagen de Airflow administrado que utiliza una versión específica de Airflow administrado.

Puedes crear un entorno de Airflow local basado en un entorno de Airflow administrado existente. En este caso, el entorno de Airflow local toma la lista de paquetes de PyPI instalados y los nombres de las variable de entorno de tu entorno de Airflow administrado.

Puedes usar este entorno de Airflow local para realizar pruebas y desarrollo, como probar código DAG nuevo, paquetes de PyPI o opciones de configuración de Airflow.

Antes de comenzar

  • La herramienta de la CLI de desarrollo local de Composer crea entornos de Airflow locales en un directorio en el que ejecutas el comando composer-dev create. Para acceder a tu entorno de Airflow local más adelante, ejecuta los comandos de la herramienta en la ruta de acceso en la que creaste el entorno local inicialmente. Todos los datos del entorno local se almacenan en un subdirectorio en la ruta de acceso en la que creaste el entorno local: ./composer/<local_environment_name>.

  • Tu computadora debe tener suficiente espacio en el disco para almacenar imágenes de Airflow administrado. La herramienta de la CLI de desarrollo local de Composer almacena un archivo de imagen para cada versión de Airflow administrado. Por ejemplo, si tienes dos entornos de Airflow locales con diferentes versiones de Airflow administrado, la herramienta de la CLI de desarrollo local de Composer almacena dos imágenes de Airflow administrado.

  • La herramienta de la CLI de desarrollo local de Composer usa una salida con colores. Puedes desactivar la salida con colores con la NO_COLOR=1 variable: NO_COLOR=1 composer-dev <other commands>.

  • Si solo tienes un entorno local, puedes omitir el nombre del entorno local de todos los comandos composer-dev, excepto run-airflow-cmd.

  • Instala las dependencias de la herramienta de la CLI de desarrollo local de Composer:

  • Instala Docker. Docker debe estar instalado y ejecutándose en el sistema local. Para verificar que Docker se esté ejecutando, puedes ejecutar cualquier comando de la CLI de Docker, como docker ps.

Configura las credenciales

Si aún no lo hiciste, obtén credenciales de usuario nuevas para usar con las credenciales predeterminadas de la aplicación:

gcloud auth application-default login

Accede a gcloud CLI con tu Cuenta de Google:

gcloud auth login

Todas las llamadas a la API que realiza la herramienta de la CLI de desarrollo local de Composer y los DAG se ejecutan desde la cuenta que usas en la gcloud CLI. Por ejemplo, si un DAG en tu entorno de Airflow local lee el contenido de un bucket de Cloud Storage, esta cuenta debe tener permisos para acceder al bucket. Esto es diferente de los entornos de Airflow administrado, en los que la cuenta de servicio de un entorno realiza las llamadas.

Instala la herramienta de la CLI de desarrollo local de Composer

Clona el repositorio de la CLI de desarrollo local de Composer:

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

En el directorio de nivel superior del repositorio clonado, ejecuta lo siguiente:

pip install .

Según tu configuración de pip, es posible que la ruta de acceso en la que se instala la herramienta no esté en la variable PATH. Si este es el caso, pip muestra un mensaje de advertencia. Puedes usar la información de este mensaje de advertencia para agregar este directorio a la variable PATH en tu sistema operativo.

Crea un entorno de Airflow local con una imagen de Airflow administrado

Para enumerar las imágenes de Airflow administrado disponibles, ejecuta lo siguiente:

composer-dev list-available-versions --include-past-releases --limit 10

Para crear un entorno de Airflow local con parámetros predeterminados, ejecuta lo siguiente:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

Otros parámetros:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

Reemplaza lo siguiente:

  • IMAGE_VERSION por el nombre de la imagen de Airflow administrado.
  • PROJECT_ID por el ID del proyecto.
  • WEB_SERVER_PORT por el puerto en el que debe escuchar el servidor web de Airflow.
  • LOCAL_DAGS_PATH por la ruta de acceso a un directorio local en el que se encuentran los archivos DAG.
  • LOCAL_ENVIRONMENT_NAME por el nombre de este entorno de Airflow local.

Ejemplo:

composer-dev create \
  --from-image-version composer-2.17.3-airflow-2.11.1 \
  example-local-environment

Crea un entorno de Airflow local a partir de un entorno de Airflow administrado

Solo se toma la siguiente información de un entorno de Airflow administrado:

  • Versiones de Airflow administrado y Airflow que se usan en tu entorno.

  • Lista de paquetes de PyPI personalizados instalados en tu entorno.

  • Lista comentada de nombres de variables de entorno configuradas en tu entorno.

No se copian otros parámetros de configuración e información del entorno, como archivos DAG, historial de ejecución de DAG, variables de Airflow y conexiones, desde tu entorno de Airflow administrado.

Para crear un entorno de Airflow local a partir de un entorno de Airflow administrado existente, haz lo siguiente:

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

Reemplaza lo siguiente:

  • LOCAL_ENVIRONMENT_NAME por un nombre para el entorno de Airflow local.
  • ENVIRONMENT_NAME por el nombre del entorno de Airflow administrado.
  • LOCATION por la región en la que se encuentra el entorno de Airflow administrado.
  • PROJECT_ID por el ID del proyecto.
  • WEB_SERVER_PORT por un puerto para el servidor web de Airflow local.
  • LOCAL_DAGS_PATH por una ruta de acceso a un directorio local en el que se encuentran los DAG.

Ejemplo:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

Inicia un entorno de Airflow local

Para iniciar un entorno de Airflow local, ejecuta lo siguiente:

composer-dev start LOCAL_ENVIRONMENT_NAME

Reemplaza lo siguiente:

  • LOCAL_ENVIRONMENT_NAME por el nombre de un entorno de Airflow local.

Detén o reinicia un entorno de Airflow local

Cuando reinicias un entorno de Airflow local, la herramienta de la CLI de desarrollo local de Composer reinicia el contenedor de Docker en el que se ejecuta el entorno. Todos los componentes de Airflow se detienen y se vuelven a iniciar. Como resultado, todas las ejecuciones de DAG que se ejecutan durante un reinicio se marcan como failed .

Para reiniciar o iniciar un entorno de Airflow local detenido, ejecuta lo siguiente:

composer-dev restart LOCAL_ENVIRONMENT_NAME

Reemplaza lo siguiente:

  • LOCAL_ENVIRONMENT_NAME por el nombre de un entorno de Airflow local.

Para detener un entorno de Airflow local, ejecuta lo siguiente:

composer-dev stop LOCAL_ENVIRONMENT_NAME

Agregar y actualizar DAG

Los DAG se almacenan en el directorio que especificaste en el parámetro --dags-path cuando creaste tu entorno de Airflow local. De forma predeterminada, este directorio es ./composer/<local_environment_name>/dags. Puedes obtener el directorio que usa tu entorno con el describe comando.

Para agregar y actualizar DAG, cambia los archivos en este directorio. No es necesario reiniciar tu entorno de Airflow local.

Visualiza los registros del entorno de Airflow local

Puedes ver los registros recientes de un contenedor de Docker que ejecuta tu entorno de Airflow local. De esta manera, puedes supervisar los eventos relacionados con el contenedor y verificar los registros de Airflow para detectar errores, como conflictos de dependencias causados por la instalación de paquetes de PyPI.

Para ver los registros de un contenedor de Docker que ejecuta tu entorno de Airflow local, ejecuta lo siguiente:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Para seguir la transmisión de registros, omite el argumento --max-lines:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Ejecuta un comando de la CLI de Airflow

Puedes ejecutar comandos de la CLI de Airflow en tu entorno de Airflow local.

Para ejecutar un comando de la CLI de Airflow, haz lo siguiente:

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

Ejemplo:

composer-dev run-airflow-cmd example-local-environment dags list -o table

Configura entornos de Airflow locales

La herramienta de la CLI de desarrollo local de Composer almacena parámetros de configuración para un entorno de Airflow local, como variables de entorno y requisitos de paquetes de PyPI en el directorio del entorno local (./composer/<local_environment_name>).

La configuración se aplica cuando se inicia un entorno de Airflow local. Por ejemplo, si agregas requisitos de paquetes de PyPI en conflicto, la herramienta de la CLI de desarrollo local de Composer informa errores cuando inicias el entorno local.

Las conexiones de Airflow se almacenan en la base de datos del entorno de Airflow local. Puedes configurarlas ejecutando un comando de la CLI de Airflow o almacenando los parámetros de conexión en variables de entorno. Para obtener más información sobre las formas de crear y configurar conexiones, consulta Administra conexiones en la documentación de Airflow.

Obtén una lista y el estado de los entornos de Airflow locales

Para enumerar todos los entornos de Airflow locales disponibles y mostrar su estado, haz lo siguiente:

composer-dev list

Para describir un entorno específico y obtener detalles como la versión de la imagen, la ruta de acceso de los DAG y la URL del servidor web de un entorno, haz lo siguiente:

composer-dev describe LOCAL_ENVIRONMENT_NAME

Reemplaza lo siguiente:

  • LOCAL_ENVIRONMENT_NAME por el nombre del entorno de Airflow local.

Enumera las imágenes que usan los entornos de Airflow locales

Para enumerar todas las imágenes que usa la herramienta de la CLI de desarrollo local de Composer, ejecuta lo siguiente:

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

Instala complementos y cambia datos

Los complementos y los datos de un entorno de Airflow local se toman del directorio del entorno local: ./composer/<local_environment_name>/data y ./composer/<local_environment_name>/plugins).

Para cambiar el contenido de los directorios /data y /plugins, agrega o quita archivos en estos directorios. Docker propaga automáticamente los cambios de archivos a tu entorno de Airflow local.

La herramienta de la CLI de desarrollo local de Composer no admite la especificación de un directorio diferente para datos y complementos.

Configure las variables de entorno

Para configurar las variables de entorno, edita el variables.env archivo en el directorio del entorno: ./composer/<local_environment_name>/variables.env.

El archivo variables.env debe contener definiciones de clave-valor, una línea para cada variable de entorno. Para cambiar las opciones de configuración de Airflow, usa el formato AIRFLOW__SECTION__KEY. Para obtener más información sobre las variables de entorno disponibles, consulta Referencia de configuración de Airflow.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

Para aplicar los cambios, reinicia tu entorno de Airflow local.

Instala o quita paquetes de PyPI

Para instalar o quitar paquetes de PyPI, modifica el requirements.txt archivo en el directorio del entorno: ./composer/<local_environment_name>/requirements.txt.

Los requisitos deben seguir el formato especificado en PEP-508 donde cada requisito se especifica en minúsculas y consta del nombre del paquete con extras opcionales y especificadores de versión.

Para aplicar los cambios, reinicia tu entorno de Airflow local.

Cambia a una imagen de Airflow administrado diferente

Puedes usar cualquier imagen de Airflow administrado con la herramienta de la CLI de desarrollo local de Composer y cambiar entre las imágenes. Este enfoque es diferente de la actualización de tu entorno de Airflow administrado, ya que los parámetros de configuración de tu entorno de Airflow local se aplican cuando se inicia.

Por ejemplo, después de que se lanza una nueva versión de Airflow administrado, puedes cambiar tu entorno para usarla y conservar la configuración existente del entorno de Airflow local. Como otro ejemplo, puedes cambiar entre diferentes versiones de Airflow dentro de una versión específica de Airflow administrado.

Para cambiar la imagen del entorno que usa tu entorno de Airflow local, haz lo siguiente:

  1. Edita el archivo de configuración del entorno local: ./composer/<local_environment_name>/config.json.

  2. Cambia el valor del parámetro composer_image_version. Para ver los valores disponibles, puedes enumerar las imágenes disponibles.

  3. Para aplicar los cambios, reinicia tu entorno de Airflow local.

Borra un entorno de Airflow local

Precaución: Asegúrate de haber guardado todos los datos requeridos del entorno, como registros y configuración.

Para borrar un entorno de Airflow local, ejecuta el siguiente comando:

composer-dev remove LOCAL_ENVIRONMENT_NAME

Si el entorno se está ejecutando, agrega la marca --force para forzar su eliminación.

Borra imágenes de Docker

Para borrar todas las imágenes descargadas por la herramienta de la CLI de desarrollo local de Composer, ejecuta lo siguiente:

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

Soluciona problemas

En esta sección, se proporcionan soluciones para problemas comunes.

No se puede iniciar un entorno local en MacOS

Si instalaste el paquete composer-dev en un directorio al que Docker no puede acceder, es posible que no se inicie tu entorno local.

Por ejemplo, si Python está instalado en el directorio /opt, como cuando lo instalas con la configuración predeterminada de Homebrew en MacOS, el paquete composer-dev también se instala en el directorio /opt. Debido a que Docker cumple con las reglas de sandbox de Apple, el directorio /opt no está disponible de forma predeterminada. Además, no puedes agregarlo a través de la IU (Configuración > Recursos > Uso compartido de archivos).

En este caso, la herramienta de la CLI de desarrollo local de Composer genera un mensaje de error similar al siguiente ejemplo:

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

Puedes usar una de las siguientes soluciones:

  • Instala Python o el paquete composer-dev en un directorio diferente para que Docker pueda acceder al paquete.
  • Edita de forma manual el archivo ~/Library/Group\ Containers/group.com.docker/settings.json y agrega /opt a filesharingDirectories.

¿Qué sigue?