Prueba, sincroniza e implementa tus DAG desde GitHub

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

En esta guía, se explica cómo crear una canalización de CI/CD para probar, sincronizar e implementar DAG en tu entorno de Airflow administrado desde tu repositorio de GitHub.

Si solo quieres sincronizar datos de otros servicios, consulta Transfiere datos de otros servicios.

Descripción general de la canalización de CI/CD

Figura 1: Diagrama de arquitectura que muestra los pasos del el flujo (haz clic para ampliar)

La canalización de CI/CD para probar, sincronizar e implementar DAG tiene los siguientes pasos:

1. Realizas un cambio en un DAG y lo envías a una rama de desarrollo en tu repositorio.

2. Abres una solicitud de extracción en la rama principal de tu repositorio.

3. Cloud Build ejecuta pruebas de unidades para verificar que tu DAG sea válido.

4. Se aprueba tu solicitud de extracción y se combina con la rama principal de tu repositorio.

5. Cloud Build sincroniza tu entorno de Airflow administrado de desarrollo con estos cambios nuevos.

6. Verificas que el DAG funcione como se espera en tu entorno de desarrollo

7. Si tu DAG funciona como se espera, lo subes a tu entorno de Airflow administrado de producción.

Objetivos

• Ejecuta una verificación previa al envío automatizada con Cloud Build. Esta verificación ejecuta pruebas de unidades para un DAG.
• Sincroniza los DAG en tu entorno de Managed Service para Apache Airflow de desarrollo con los DAG en tu repositorio de GitHub.

Antes de comenzar

• En esta guía, se supone que trabajas con dos entornos de Airflow administrado idénticos: un entorno de desarrollo y un entorno de producción.

  Para los fines de esta guía, configurarás una canalización de CI/CD solo para el entorno de desarrollo. Asegúrate de que el entorno que usas no sea un entorno de producción.

• En esta guía, se supone que tienes tus DAG y sus pruebas almacenados en un repositorio de GitHub.

  La canalización de CI/CD de ejemplo muestra el contenido de un repositorio de ejemplo. Los DAG y las pruebas se almacenan en el directorio dags/, con archivos de requisitos, el archivo de restricciones y los archivos de configuración de compilación de Cloud Build almacenados en el nivel superior. La utilidad de sincronización de DAG y sus requisitos se encuentran en el directorio utils.

Crea un trabajo de verificación previa al envío y pruebas de unidades

El primer trabajo de Cloud Build ejecuta una verificación previa al envío, que ejecuta pruebas de unidades para tus DAG.

Agrega pruebas de unidades

Si aún no lo hiciste, crea pruebas de unidades para tus DAG. Guarda estas pruebas junto con los DAG en tu repositorio, cada una con el sufijo _test. Por ejemplo, el archivo de prueba para el DAG en example_dag.py es example_dag_test.py. Estas son las pruebas que se ejecutan como una verificación previa al envío en tu repositorio.

Crea la configuración YAML de Cloud Build para la verificación previa al envío

En tu repositorio, crea un archivo YAML llamado test-dags.cloudbuild.yaml que configure tu trabajo de Cloud Build para las verificaciones previas al envío. En él, hay tres pasos:

1. Instala las dependencias que necesitan tus DAG.
2. Instala las dependencias que necesitan tus pruebas de unidades.
3. Ejecuta las pruebas de DAG.

steps:
  # install dependencies
  - name: python:3.8-slim
    entrypoint: pip
    args: ["install", "-r", "requirements.txt", "-c", "constraints.txt", "--user"]

  - name: python:3.8-slim
    entrypoint: pip
    args: ["install", "-r", "requirements-test.txt", "--user"]

  # run in python 3.8 which is latest version in Cloud Composer
  - name: python:3.8-slim
    entrypoint: python3.8
    args: ["-m", "pytest", "-s", "dags/"]

Nota: Cloud Build extrae la imagen de Python de Docker Hub y puedes especificar la etiqueta en el campo name de cada paso. Si usas python como tu entrypoint, asegúrate de que tu entrypoint coincida con la versión especificada en tu etiqueta; de lo contrario, entrypoint se establece de forma predeterminada en latest.

Crea el activador de compilación de Cloud Build para la verificación previa al envío

Sigue la guía Compila repositorios desde GitHub para crear un activador basado en la app de GitHub con las siguientes configuraciones:

• Nombre: test-dags

• Evento: Solicitud de extracción

• Fuente : Repositorio: Elige tu repositorio

• Fuente : Rama base: ^main$ (cambia main por el nombre de la rama base de tu repositorio, si es necesario)

• Fuente : Control de comentarios: No es obligatorio

  **Precaución:** Si configuras el Control de comentarios como no obligatorio, significa que cualquier usuario puede enviar una solicitud de extracción que active la compilación. Para repositorios más grandes o repositorios con colaboradores no confiables, se recomienda requerir el Control de comentarios.

• Configuración de compilación : Archivo de configuración de Cloud Build: /test-dags.cloudbuild.yaml (la ruta de acceso a tu archivo de compilación)

Crea un trabajo de sincronización de DAG y agrega una secuencia de comandos de utilidad de DAG

A continuación, configura un trabajo de Cloud Build que ejecute una secuencia de comandos de utilidad de DAG. La secuencia de comandos de utilidad de este trabajo sincroniza tus DAG con tu entorno de Airflow administrado después de que se combinan con la rama principal de tu repositorio.

Nota: Airflow administrado analiza todos los DAG en un intervalo repetido. Esto sucede incluso si los DAG no cambiaron desde el último análisis. Debido a este comportamiento, esta utilidad sube todos los DAG a Airflow administrado, no solo los que cambiaron.

Agrega la secuencia de comandos de utilidad de DAG

Agrega la secuencia de comandos de utilidad de DAG a tu repositorio. Esta secuencia de comandos de utilidad copia todos los archivos DAG en el directorio dags/ de tu repositorio a un directorio temporal, ignorando todos los archivos Python que no sean DAG. Luego, la secuencia de comandos usa la biblioteca cliente de Cloud Storage para subir todos los archivos de ese directorio temporal al directorio dags/ en el bucket de tu entorno de Airflow administrado.

from __future__ import annotations

import argparse
import glob
import os
from shutil import copytree, ignore_patterns
import tempfile

# Imports the Google Cloud client library
from google.cloud import storage


def _create_dags_list(dags_directory: str) -> tuple[str, list[str]]:
    temp_dir = tempfile.mkdtemp()

    # ignore non-DAG Python files
    files_to_ignore = ignore_patterns("__init__.py", "*_test.py")

    # Copy everything but the ignored files to a temp directory
    copytree(dags_directory, f"{temp_dir}/", ignore=files_to_ignore, dirs_exist_ok=True)

    # The only Python files left in our temp directory are DAG files
    # so we can exclude all non Python files
    dags = glob.glob(f"{temp_dir}/*.py")
    return (temp_dir, dags)


def upload_dags_to_composer(
    dags_directory: str, bucket_name: str, name_replacement: str = "dags/"
) -> None:
    """
    Given a directory, this function moves all DAG files from that directory
    to a temporary directory, then uploads all contents of the temporary directory
    to a given cloud storage bucket
    Args:
        dags_directory (str): a fully qualified path to a directory that contains a "dags/" subdirectory
        bucket_name (str): the GCS bucket of the Cloud Composer environment to upload DAGs to
        name_replacement (str, optional): the name of the "dags/" subdirectory that will be used when constructing the temporary directory path name Defaults to "dags/".
    """
    temp_dir, dags = _create_dags_list(dags_directory)

    if len(dags) > 0:
        # Note - the GCS client library does not currently support batch requests on uploads
        # if you have a large number of files, consider using
        # the Python subprocess module to run gcloud storage cp --recursive on your dags
        # See https://cloud.google.com/storage/docs/gsutil/commands/cp for more info
        storage_client = storage.Client()
        bucket = storage_client.bucket(bucket_name)

        for dag in dags:
            # Remove path to temp dir
            dag = dag.replace(f"{temp_dir}/", name_replacement)

            try:
                # Upload to your bucket
                blob = bucket.blob(dag)
                blob.upload_from_filename(dag)
                print(f"File {dag} uploaded to {bucket_name}/{dag}.")
            except FileNotFoundError:
                current_directory = os.listdir()
                print(
                    f"{name_replacement} directory not found in {current_directory}, you may need to override the default value of name_replacement to point to a relative directory"
                )
                raise

    else:
        print("No DAGs to upload.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument(
        "--dags_directory",
        help="Relative path to the source directory containing your DAGs",
    )
    parser.add_argument(
        "--dags_bucket",
        help="Name of the DAGs bucket of your Composer environment without the gs:// prefix",
    )

    args = parser.parse_args()

    upload_dags_to_composer(args.dags_directory, args.dags_bucket)

Crea la configuración YAML de Cloud Build para sincronizar DAG

En tu repositorio, crea un archivo YAML llamado add-dags-to-composer.cloudbuild.yaml que configure tu trabajo de Cloud Build para sincronizar DAG. En él, hay dos pasos:

1. Instala las dependencias que necesita la secuencia de comandos de utilidad de DAG.

2. Ejecuta la secuencia de comandos de utilidad para sincronizar los DAG en tu repositorio con tu entorno de Airflow administrado.

steps:
  # install dependencies
  - name: python
    entrypoint: pip
    args: ["install", "-r", "utils/requirements.txt", "--user"]

  # run
  - name: python
    entrypoint: python
    args: ["utils/add_dags_to_composer.py", "--dags_directory=${_DAGS_DIRECTORY}", "--dags_bucket=${_DAGS_BUCKET}"]

Nota: Cloud Build extrae la imagen de Python de Docker Hub y puedes especificar la etiqueta en el campo name de cada paso. Si usas python como tu entrypoint, asegúrate de que tu entrypoint coincida con la versión especificada en tu etiqueta; de lo contrario, entrypoint se establece de forma predeterminada en latest.

Crea el activador de compilación de Cloud Build

Sigue la guía Compila repositorios desde GitHub para crear un activador basado en la app de GitHub con las siguientes configuraciones:

• Nombre: add-dags-to-composer

• Evento: Enviar a una rama

• Fuente : Repositorio: Elige tu repositorio

• Fuente : Rama base: ^main$ (cambia main por el nombre de la rama base de tu repositorio, si es necesario)

• Fuente : Filtro de archivos incluidos (glob): dags/**

• Configuración de compilación - Archivo de configuración de Cloud Build: /add-dags-to-composer.cloudbuild.yaml (la ruta de acceso a tu archivo de compilación)

En la Configuración avanzada, agrega dos variables de sustitución:

• _DAGS_DIRECTORY - El directorio donde se encuentran los DAG en tu repositorio. Si usas el repositorio de ejemplo de esta guía, es dags/.

• _DAGS_BUCKET - El bucket de Cloud Storage que contiene el dags/ directorio en tu entorno de Airflow administrado de desarrollo. Omite el prefijo gs://. Por ejemplo: us-central1-example-env-1234ab56-bucket.

Precaución: Si no quitas el sufijo dags/ del nombre del bucket de Cloud Storage en la variable de sustitución _DAGS_BUCKET, el trabajo de sincronización de DAG falla con un error NotFound. Esto sucede porque, en Cloud Storage, dags/ es una carpeta, que se considera parte del nombre del objeto, no parte del nombre del bucket.

Prueba tu canalización de CI/CD

En esta sección, sigue un flujo de desarrollo de DAG que utiliza los activadores de Cloud Build que creaste recientemente.

Ejecuta un trabajo previo al envío

Crea una solicitud de extracción en tu rama principal para probar tu compilación. Ubica la verificación previa al envío en la página. Haz clic en Detalles y elige Ver más detalles en Google Cloud Build para ver los registros de compilación en la Google Cloud consola.

Importante: Cloud Build ejecuta pruebas de unidades con paquetes especificados en requirements.txt y requirements-test.txt, que incluyen una versión pública de Airflow. Es posible que tu entorno de Airflow administrado tenga un conjunto diferente de paquetes de PyPI y paquetes preinstalados. Te recomendamos que ejecutes un entorno de Airflow local mientras desarrollas tus DAG.

Figura 2: Captura de pantalla del estado de la verificación previa al envío de Cloud Build en GitHub (haz clic para ampliar)

Si falló la verificación previa al envío, consulta Cómo abordar las fallas de compilación.

Valida que tu DAG funcione en tu entorno de desarrollo

Después de que se apruebe tu solicitud de extracción, combínala con tu rama principal. Usa la Google Cloud consola para ver los resultados de la compilación. Si tienes muchos activadores de Cloud Build, puedes filtrar tus compilaciones por el nombre del activador add-dags-to-composer.

Después de que el trabajo de sincronización de Cloud Build se realice correctamente, el DAG sincronizado aparecerá en tu entorno de Airflow administrado de desarrollo. Allí, puedes validar que el DAG funcione como se espera.

Agrega el DAG a tu entorno de producción

Después de que el DAG funcione como se espera, agrégalo manualmente a tu entorno de producción. Para ello, sube el archivo DAG al directorio dags/ en el bucket de tu entorno de Airflow administrado de producción.

Si falló el trabajo de sincronización de DAG o si tu DAG no se comporta como se espera en tu entorno de Airflow administrado de desarrollo, consulta Cómo abordar las fallas de compilación.

Cómo abordar las fallas de compilación

En esta sección, se explica cómo abordar situaciones comunes de fallas de compilación.

¿Qué sucede si falla la verificación previa al envío?

En tu solicitud de extracción, haz clic en Detalles y elige Ver más detalles en Google Cloud Build para ver los registros de compilación en la Google Cloud consola. Usa estos registros para depurar el problema con tu DAG. Una vez que hayas resuelto los problemas, confirma la corrección y envíala a tu rama. La verificación previa al envío se ejecuta de nuevo y puedes seguir iterando con los registros como herramienta de depuración.

¿Qué sucede si falla mi trabajo de sincronización de DAG?

Usa la Google Cloud consola para ver los resultados de la compilación. Si tienes muchos activadores de Cloud Build, puedes filtrar tus compilaciones por el nombre del activador add-dags-to-composer. Examina los registros del trabajo de compilación y resuelve los errores. Si necesitas ayuda adicional para resolver los errores, usa los canales de asistencia.

¿Qué sucede si mi DAG no funciona correctamente en mi entorno de Airflow administrado?

Si tu DAG no funciona como se espera en tu entorno de Airflow administrado de desarrollo, no lo promuevas manualmente a tu entorno de Airflow administrado de producción. Como alternativa, toma una de las siguientes medidas:

• Revierte la solicitud de extracción con los cambios que interrumpieron tu DAG para restablecerlo al estado inmediatamente anterior a los cambios (esto también revierte todos los demás archivos de esa solicitud de extracción).
• Crea una nueva solicitud de extracción para revertir manualmente los cambios en el DAG interrumpido.
• Crea una nueva solicitud de extracción para corregir los errores en tu DAG.

Si sigues alguno de estos pasos, se activará una nueva verificación previa al envío y, cuando se combine, el trabajo de sincronización de DAG.

¿Qué sigue?

• Ejecuta entornos de Airflow locales
• Escribe DAG
• Programa y activa DAG
• Prueba DAG