Ejecutar un entorno local de Airflow con la herramienta de línea de comandos de desarrollo local de Composer

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

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

Acerca de la herramienta de CLI de desarrollo local de Composer

La herramienta de línea de comandos de desarrollo local de Composer simplifica el desarrollo de DAGs de Apache Airflow para Cloud Composer ejecutando un entorno de Airflow de forma local. Este entorno local de Airflow usa una imagen de compilación de Airflow que utiliza una versión de Cloud Composer específica.

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

Puedes usar este entorno local de Airflow para hacer pruebas y desarrollar, por ejemplo, para probar código DAG nuevo, paquetes PyPI u opciones de configuración de Airflow.

Antes de empezar

  • La herramienta de 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 local de Airflow más adelante, ejecuta los comandos de la herramienta en la ruta en la que creaste el entorno local inicialmente. Todos los datos del entorno local se almacenan en un subdirectorio de la ruta en la que has creado el entorno local: ./composer/<local_environment_name>.

  • Tu ordenador debe tener suficiente espacio en el disco para almacenar imágenes de compilación de Airflow. La herramienta CLI de desarrollo local de Composer almacena un archivo de imagen por cada compilación de Airflow. Por ejemplo, si tienes dos entornos locales de Airflow con diferentes compilaciones de Airflow, la herramienta de línea de comandos de desarrollo local de Composer almacenará dos imágenes de compilación de Airflow.

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

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

  • Instala las dependencias de la herramienta de línea de comandos de desarrollo local de Composer:

  • Instala Docker, una plataforma Docker debe estar instalado y en ejecución en el sistema local. Para comprobar que Docker está en funcionamiento, puedes ejecutar cualquier comando de la CLI de Docker, como docker ps.

Configurar credenciales

Si aún no lo has hecho, obtén las credenciales de usuario que vas a usar para las credenciales predeterminadas de la aplicación:

gcloud auth application-default login

Inicia sesión en gcloud CLI con tu cuenta de Google:

gcloud auth login

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

Instalar la herramienta de 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 el siguiente comando:

pip install .

En función de la configuración de pip, es posible que la ruta en la que se instala la herramienta no esté en la variable PATH. Si es así, pip mostrará un mensaje de advertencia. Puedes usar la información de este mensaje de advertencia para añadir este directorio a la variable PATH de tu sistema operativo.

Crear un entorno de Airflow local con una imagen de compilación de Airflow

Para enumerar las imágenes de compilación de Airflow disponibles, ejecuta el siguiente comando:

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

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

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

Sustituye:

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

Ejemplo:

composer-dev create \
  --from-image-version composer-3-airflow-2.10.5-build.11 \
  example-local-environment

Crear un entorno de Airflow local a partir de un entorno de Cloud Composer

Solo se toma la siguiente información de un entorno de Cloud Composer:

  • Compilación específica de Airflow que usa tu entorno.

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

  • Lista comentada de los nombres de las variables de entorno definidas en tu entorno.

No se copia otra información ni otros parámetros de configuración del entorno, como los archivos DAG, el historial de ejecuciones de DAG, las variables de Airflow y las conexiones, de tu entorno de Cloud Composer.

Para crear un entorno de Airflow local a partir de un entorno de Cloud Composer, sigue estos pasos:

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

Sustituye:

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

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

Iniciar un entorno de Airflow local

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

composer-dev start LOCAL_ENVIRONMENT_NAME

Sustituye:

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

Detener o reiniciar un entorno local de Airflow

Cuando reinicias un entorno local de Airflow, la herramienta CLI de desarrollo local de Composer reinicia el contenedor Docker en el que se ejecuta el entorno. Todos los componentes de Airflow se detienen y se vuelven a iniciar. Por lo tanto, todas las ejecuciones de DAG que se realicen durante un reinicio se marcarán como fallidas .

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

composer-dev restart LOCAL_ENVIRONMENT_NAME

Sustituye:

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

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

composer-dev stop LOCAL_ENVIRONMENT_NAME

Añadir y actualizar DAGs

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

Para añadir y actualizar DAGs, cambia los archivos de este directorio. No es necesario que reinicies tu entorno local de Airflow.

Ver los registros del entorno de Airflow local

Puedes ver los registros recientes de un contenedor Docker que ejecuta tu entorno local de Airflow. De esta forma, puedes monitorizar los eventos relacionados con los contenedores y consultar 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 Docker que ejecuta tu entorno de Airflow local, ejecuta el siguiente comando:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Para seguir el flujo de registros, omite el argumento --max-lines:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Ejecutar un comando de la CLI de Airflow

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

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

Configurar entornos locales de Airflow

La herramienta de línea de comandos de desarrollo local de Composer almacena los parámetros de configuración de un entorno de Airflow local, como las variables de entorno y los requisitos de los 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 añades requisitos de paquetes de PyPI que entran en conflicto, la herramienta de línea de comandos de desarrollo local de Composer mostrará errores cuando inicies el entorno local.

Las conexiones de Airflow se almacenan en la base de datos del entorno local de Airflow. 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 Gestionar conexiones en la documentación de Airflow.

Obtener una lista y el estado de los entornos de Airflow locales

Para enumerar todos los entornos locales de Airflow disponibles y mostrar su estado, sigue estos pasos:

composer-dev list

Para describir un entorno específico y obtener detalles como la versión de la imagen, la ruta de los DAGs y la URL del servidor web de un entorno, sigue estos pasos:

composer-dev describe LOCAL_ENVIRONMENT_NAME

Sustituye:

  • LOCAL_ENVIRONMENT_NAME con el nombre del entorno de Airflow local.

Lista de imágenes usadas por entornos de Airflow locales

Para enumerar todas las imágenes que usa la herramienta de línea de comandos de desarrollo local de Composer, ejecuta el siguiente comando:

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

Instalar complementos y cambiar 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, añade o elimina archivos de estos directorios. Docker propaga automáticamente los cambios en los archivos a tu entorno local de Airflow.

La herramienta CLI de desarrollo local de Composer no permite especificar un directorio diferente para los datos y los complementos.

Configurar variables de entorno

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

El archivo variables.env debe contener definiciones de clave-valor, una línea por 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 la 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 local de Airflow.

Instalar o eliminar paquetes de PyPI

Para instalar o quitar paquetes de PyPI, modifica el archivo requirements.txt 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 y especificadores de versión opcionales.

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

Cambiar a otra imagen de compilación de Airflow

Puedes usar cualquier imagen de compilación de Airflow con la herramienta de línea de comandos de desarrollo local de Composer y cambiar de una imagen a otra. Este enfoque es diferente al de actualizar tu entorno de Cloud Composer, ya que los parámetros de configuración de tu entorno de Airflow local se aplican cuando se inicia.

Por ejemplo, cuando se lance una nueva compilación de Airflow, puedes cambiar tu entorno para usarla y mantener la configuración del entorno de Airflow local.

Para cambiar la imagen del entorno que usa tu entorno de Airflow local, sigue estos pasos:

  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 listar las imágenes disponibles.

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

Eliminar un entorno de Airflow local

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

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

composer-dev remove LOCAL_ENVIRONMENT_NAME

Si el entorno está en ejecución, añade la marca --force para forzar su eliminación.

Eliminar imágenes de Docker

Para eliminar todas las imágenes descargadas por la herramienta CLI de desarrollo local de Composer, ejecuta el siguiente comando:

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

Solución de problemas

En esta sección se ofrecen soluciones a problemas habituales.

No se puede iniciar un entorno local en macOS

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

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. Como Docker cumple las reglas de entorno aislado de Apple, el directorio /opt no está disponible de forma predeterminada. Además, no puedes añadirlo a través de la interfaz de usuario (Configuración > Recursos > Uso compartido de archivos).

En este caso, la herramienta 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 otro directorio para que Docker pueda acceder al paquete.
  • Edita manualmente el archivo ~/Library/Group\ Containers/group.com.docker/settings.json y añade /opt a filesharingDirectories.

Siguientes pasos