Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3
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 Cloud Composer mediante la ejecución de un entorno de Airflow de forma local. Este entorno local de Airflow usa una imagen de una versión específica de Cloud Composer.
Puedes crear un entorno local de Airflow basado en un entorno de Cloud Composer existente. En este caso, el entorno local de Airflow toma la lista de paquetes de PyPI instalados y los nombres de variable de entorno de tu entorno de Cloud Composer.
Puedes usar este entorno local de Airflow con fines de prueba y desarrollo, por ejemplo, para probar un nuevo código DAG, paquetes de PyPI o, también, 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 local de Airflow más tarde, 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 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 Cloud Composer. La herramienta de la CLI de desarrollo local de Composer almacena un archivo de imagen para cada versión de Cloud Composer. Por ejemplo, si tienes dos entornos locales de Airflow con diferentes versiones de Cloud Composer, la herramienta de la CLI de desarrollo local de Composer almacena dos imágenes de Cloud Composer.
La herramienta de la CLI de desarrollo local de Composer usa resultados coloreados. Puedes inhabilitar los resultados coloreados 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 de todos los comandos de
composer-dev
, exceptorun-airflow-cmd
.Instala las dependencias de la herramienta de la CLI de desarrollo local de Composer:
- Python versiones 3.7 a 3.10 con
pip
- Google Cloud CLI
- Python versiones 3.7 a 3.10 con
Instala Docker. Docker debe estar instalado y ejecutarse en el sistema local. Para verificar que Docker esté en ejecución, puedes ejecutar cualquier comando de la CLI de Docker, como
docker ps
.
Configura las credenciales
Si aún no lo hiciste, obtén nuevas credenciales de usuario para usarlas en 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 realizadas por la herramienta de la CLI de desarrollo local de Composer y los DAG se ejecutan desde la cuenta que usas en gcloud CLI. Por ejemplo, si un DAG en tu entorno local de Airflow 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 Cloud Composer, 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 la configuración de pip
, es posible que la ruta en la que está instalada 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 versión específica de Cloud Composer
Para enumerar las versiones disponibles de Cloud Composer, ejecuta el siguiente comando:
composer-dev list-available-versions --include-past-releases --limit 10
Para crear un entorno local de Airflow 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
Reemplaza lo siguiente:
IMAGE_VERSION
por el nombre de la imagen de Cloud Composer.PROJECT_ID
por el ID del proyecto.WEB_SERVER_PORT
por el puerto en el que debe escuchar el servidor web de AirflowLOCAL_DAGS_PATH
por la ruta a un directorio local en el que se encuentran los archivos DAGLOCAL_ENVIRONMENT_NAME
por el nombre de este entorno local de Airflow
Ejemplo:
composer-dev create \
--from-image-version composer-2.8.3-airflow-2.7.3 \
example-local-environment
Crea un entorno de Airflow local desde un entorno de Cloud Composer
Solo se toma la siguiente información del entorno de Cloud Composer:
- Versión de la imagen (versiones de Cloud Composer y Airflow que se usan en tu entorno)
- Lista de paquetes personalizados de PyPI instalados en tu entorno.
Lista con comentarios de nombres de variables de entorno configuradas en tu entorno.
Otra información y parámetros de configuración del entorno, como los archivos DAG, el historial de ejecuciones de DAG, las variables de Airflow y las conexiones, no se copian de tu entorno de Cloud Composer.
Para crear un entorno de Airflow local desde un entorno existente 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
Reemplaza lo siguiente:
LOCAL_ENVIRONMENT_NAME
por un nombre para el entorno local de AirflowENVIRONMENT_NAME
por el nombre del entorno de Cloud ComposerLOCATION
por la región en la que se encuentra el entorno de Cloud ComposerPROJECT_ID
por el ID del proyecto.WEB_SERVER_PORT
por un puerto para el servidor web local de AirflowLOCAL_DAGS_PATH
por una ruta 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 local de Airflow
Para iniciar un entorno local de Airflow, ejecuta el siguiente comando:
composer-dev start LOCAL_ENVIRONMENT_NAME
Reemplaza lo siguiente:
LOCAL_ENVIRONMENT_NAME
por el nombre de un entorno local de Airflow
Detén o reinicia un entorno local de Airflow
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 con errores .
Para reiniciar o iniciar un entorno de Airflow local detenido, ejecuta el siguiente comando:
composer-dev restart LOCAL_ENVIRONMENT_NAME
Reemplaza lo siguiente:
LOCAL_ENVIRONMENT_NAME
por el nombre de un entorno local de Airflow
Para detener un entorno local de Airflow, ejecuta el siguiente comando:
composer-dev stop LOCAL_ENVIRONMENT_NAME
Agrega y actualiza DAG
Los DAG 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 agregar y actualizar DAG, cambia los archivos en este directorio. No es necesario que reinicies tu entorno local de Airflow.
Consulta los registros del entorno de Airflow local
Puedes ver los registros recientes desde un contenedor de Docker que ejecute tu entorno de Airflow local. De esta manera, puedes supervisar los eventos relacionados con el contenedor y verificar los registros de Airflow en busca de errores, como conflictos de dependencias causados por la instalación de paquetes de PyPI.
Para ver los registros desde un contenedor de Docker que ejecuta el entorno local de Airflow, ejecuta el siguiente comando:
composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10
Para seguir la secuencia de registro, omite el argumento --max-lines
:
composer-dev logs LOCAL_ENVIRONMENT_NAME
Ejecuta un comando de la CLI de Airflow
Puedes ejecutar los comandos de la CLI de Airflow en tu entorno local de Airflow.
Para ejecutar un comando de la CLI de Airflow, sigue estos pasos:
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 locales de Airflow
La herramienta de la CLI de desarrollo local de Composer almacena los parámetros de configuración para un entorno de Airflow local, como las variables de entorno y los requisitos del paquete de PyPI en el directorio del entorno local (./composer/<local_environment_name>
).
La configuración se aplica cuando se inicia un entorno local de Airflow. Por ejemplo, si agregas requisitos de paquete 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 local de Airflow. Para configurarlos, ejecuta un comando de la CLI de Airflow o almacena los parámetros de conexión en variables de entorno. Para obtener más información sobre cómo crear y configurar conexiones, consulta Administra conexiones en la documentación de Airflow.
Obtén una lista y el estado de los entornos locales de Airflow
Para enumerar todos los entornos locales de Airflow disponibles y ver sus estados, 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 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 local de Airflow
Enumerar las imágenes que usan los entornos locales de Airflow
Para mostrar una lista de todas las imágenes que usa la herramienta de la CLI de desarrollo local de Composer, ejecuta el siguiente comando:
docker images --filter=reference='*/cloud-airflow-releaser/*/*'
Instala complementos y cambia los datos
Los complementos y los datos de un entorno de Airflow local se obtienen 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 archivo a tu entorno local de Airflow.
La herramienta de la CLI de desarrollo local de Composer no admite que se especifique un directorio diferente para datos y complementos.
Configura las variables de entorno
Para configurar las variables de entorno, edita el archivo variables.env
en el directorio de entorno:
./composer/<local_environment_name>/variables.env
.
El archivo variables.env
debe contener definiciones de pares 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 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.
Instala o quita 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, en el que 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 local de Airflow.
Cambia a otra imagen de Cloud Composer
Puedes usar cualquier imagen de Cloud Composer con la herramienta de la CLI de desarrollo local de Composer y alternar entre las imágenes. Este enfoque es diferente de actualizar el entorno de Cloud Composer, ya que los parámetros de configuración del entorno local de Airflow se aplican cuando este se inicia.
Por ejemplo, después de que se lanza una versión nueva de Cloud Composer, puedes cambiar el entorno para usar la versión nueva y mantener la configuración del entorno local de Airflow existente. Como otro ejemplo, puedes alternar entre diferentes versiones de Airflow dentro de una versión específica de Cloud Composer.
Sigue estos pasos para cambiar la imagen del entorno que usa tu entorno local de Airflow:
Edita el archivo de configuración del entorno local:
./composer/<local_environment_name>/config.json
.Cambia el valor del parámetro
composer_image_version
. Para ver los valores disponibles, puedes enumerar las versiones disponibles de Cloud Composer.Para aplicar los cambios, reinicia tu entorno local de Airflow.
Borra un entorno local de Airflow
Precaución: Asegúrate de haber guardado todos los datos necesarios del entorno, como los registros y la 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 las imágenes de Docker
Para borrar todas las imágenes que descargó la herramienta de la CLI de desarrollo local de Composer, ejecuta el siguiente comando:
docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)
Soluciona problemas
En esta sección, se proporcionan soluciones a problemas habituales.
No se puede iniciar un entorno local en macOS
Si instalaste el paquete composer-dev
en un directorio donde 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 instalará en el directorio /opt
. Debido a que Docker cumple con las reglas de la zona de pruebas 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 el archivo
~/Library/Group\ Containers/group.com.docker/settings.json
de forma manual y agrega/opt
afilesharingDirectories
.