Convertir una tubería en un proyecto en paquete

Puede convertir una canalización existente en un proyecto de paquetes de automatización declarativa. Las agrupaciones permiten definir y administrar la configuración de procesamiento de datos de Azure Databricks en un único archivo YAML controlado por código fuente que proporciona un mantenimiento más sencillo y permite la implementación automatizada en entornos de destino.

Para ver un tutorial que usa databricks pipelines comandos para crear un proyecto de canalizaciones, a continuación, implementa y ejecuta una canalización, consulte Desarrollo de canalizaciones con agrupaciones de automatización declarativa.

Introducción al proceso de conversión

Diagrama en el que se muestran los pasos específicos para convertir una canalización existente en una agrupación

Los pasos para convertir una canalización existente en un paquete son:

  1. Asegúrese de disponer de acceso a una pipeline configurada previamente que desea convertir en un paquete.
  2. Cree o prepare una carpeta (preferiblemente en una jerarquía con control de la fuente) para almacenar el conjunto.
  3. Genera una configuración para el paquete a partir de la canalización existente utilizando la CLI de Databricks.
  4. Revise la configuración de agrupación generada para asegurarse de que está completa.
  5. Vincule el paquete al pipeline original.
  6. Implemente el pipeline en un área de trabajo de destino mediante la configuración del paquete.

Requisitos

Antes de comenzar, debes tener:

Paso 1: Configurar una carpeta para el proyecto de agrupación

Debe tener acceso a un repositorio de Git que esté configurado en Azure Databricks como una carpeta de Git. Creará el proyecto de agrupación en este repositorio, que aplicará el control de código fuente y lo pondrá a disposición de otros colaboradores a través de una carpeta Git en el área de trabajo de Azure Databricks correspondiente. (Para más información sobre las carpetas de Git, consulte Carpetas de Git de Azure Databricks).

  1. Vaya a la raíz del repositorio Git clonado en su máquina local.

  2. En un lugar adecuado en la jerarquía de carpetas, cree una carpeta específicamente para el proyecto de agrupación. Por ejemplo:

    mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle

  3. Cambie el directorio de trabajo actual a esta nueva carpeta. Por ejemplo:

    cd ~/source/my-pipelines/ingestion/events/my-bundle

  4. Inicialice una nueva agrupación mediante la ejecución de:

    databricks bundle init

    Responda a las indicaciones. Una vez completado, tendrá un archivo de configuración de proyecto denominado databricks.yml en la nueva carpeta principal del proyecto. Este archivo es necesario para implementar la canalización desde la línea de comandos. Para obtener más información sobre este archivo de configuración, consulte Configuración de agrupaciones de Automatización declarativa.

Paso 2: Generación de la configuración de canalización

Desde este nuevo directorio en el árbol de carpetas del repositorio Git clonado, ejecute el comando bundle generate de la CLI de Databricks, proporcionando el ID de su canalización como <pipeline-id>:

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

Al ejecutar el comando generate, se crea un archivo de configuración de agrupación para la canalización en la carpeta resources de la agrupación y se descargan en la carpeta src los artefactos a los que se hace referencia. La --profile (o -p marca) es opcional, pero si tiene un perfil de configuración específico de Databricks (definido en el archivo .databrickscfg creado al instalar la CLI de Databricks) que prefiere usar en lugar del perfil predeterminado, inclúyalo en este comando. Para más información sobre los perfiles de configuración de Databricks, consulte Perfiles de configuración de Azure Databricks.

Sugerencia

Si tiene un proyecto de canalizaciones declarativas (SDP) de Spark existente (tiene un spark-pipeline.yml archivo), puede copiar ese proyecto de canalización en la src carpeta del lote y, a continuación, usar el databricks pipelines generate comando para generar la configuración del lote. Consulte databricks pipelines generate.

Paso 3: Revisar los archivos del proyecto de agrupación

Cuando se complete el comando bundle generate, habrá creado dos carpetas nuevas:

  • resources es el subdirectorio del proyecto que contiene archivos de configuración del proyecto.
  • src es la carpeta del proyecto donde se almacenan los archivos de origen, como consultas y cuadernos.

El comando también crea algunos archivos adicionales:

  • *.pipeline.yml en el subdirectorio resources. Este archivo contiene la configuración y las opciones específicas de la canalización.
  • Archivos de origen, como consultas SQL en el subdirectorio src, copiados de la canalización existente.
├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Paso 4: Enlace de la canalización de agrupación a la canalización existente

Debe vincular o enlazar la definición de la canalización en el conjunto a la canalización existente para mantenerla actualizada a medida que realice cambios. Para ello, ejecute el comando de vinculación de bundle deployment de la CLI de Databricks:

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> es el nombre de la canalización. Este nombre debe ser el mismo que el valor de la cadena con prefijo del nombre de archivo para la configuración de la canalización en el nuevo directorio resources. Por ejemplo, si tiene un archivo de configuración de canalización denominado ingestion_data_pipeline.pipeline.yml en la carpeta resources, debe proporcionar ingestion_data_pipeline como nombre de canalización.

<pipeline-ID> es el identificador de la canalización. Es el mismo que el que copió como parte de los requisitos de estas instrucciones.

Paso 5: Despliega tu canalización usando tu nuevo paquete

Ahora, despliegue su paquete de canalizaciones en el área de trabajo de destino mediante el comando bundle deploy de la CLI de Databricks.

databricks bundle deploy --target <target-name> --profile <profile-name>

La marca --target es necesaria y debe establecerse en una cadena que coincida con un nombre de área de trabajo de destino configurado, como development o production.

Si este comando se ejecuta correctamente, ahora dispone de la configuración de la canalización en un proyecto externo, que se puede cargar en otras áreas de trabajo para ser ejecutada y compartida fácilmente con otros usuarios de Azure Databricks en su cuenta.

Promocionar entre entornos con objetivos

Un conjunto define entornos de despliegue nombrados llamados objetivos en databricks.yml, cada uno apuntando a su propio espacio de trabajo, catálogo y valores de variables. Los objetivos son cómo promueves el mismo pipeline a través del desarrollo, el staging y la producción, desplegando código fuente idéntico en cada entorno sucesivo sin editarlo:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

Lo que estableces con mode en cada objetivo cambia su comportamiento de despliegue:

  • mode: development marca un objetivo como una implementación personal e improvisada. Los recursos reciben un [dev username] prefijo y los horarios se pausan por defecto, así que tu trabajo no afecta a nadie más.
  • mode: production Desactiva esos valores de seguridad por defecto. Combinado con run_as, le permite gestionar la canalización como una entidad de servicio en lugar de una cuenta individual, así que las ejecuciones no se rompen cuando alguien deja el equipo o cambia de rol. Azure Databricks recomienda una entidad de servicio para ensayo y producción. service_principal_name toma el ID de aplicación de la entidad de servicio, no su nombre de visualización. Puedes recuperar el ID de la aplicación desde la página del responsable del servicio en la configuración de administración de tu espacio de trabajo.

Para el conjunto completo de comportamientos de modos, consulte Declarative Automation Bundles modos de despliegue y Especificar una identidad de ejecución para un flujo de trabajo de Declarative Automation Bundles.

Para promocionar, despliega el mismo paquete a cada objetivo por turno, verificando en cada etapa:

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

En lugar de codificar directamente nombres de catálogo o rutas fuente por entorno dentro de tu código de transformación, pasa los valores desde el destino para que la misma fuente se ejecute sin modificar en todas partes. Cómo los configures depende de tu idioma de origen. Los parámetros de la canalización solo se aplican al código fuente SQL. Para código fuente en Python, utiliza el campo pipeline configuration y lee los valores con spark.conf.get():

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Para obtener más información sobre la parametrización del código de canalización, consulte Usar parámetros con canalizaciones.

Configurar CI/CD

Dado que una pipeline convertida se define completamente como un bundle (YAML más archivos fuente en Git), configurar integración continua y entrega continua (CI/CD) para ella significa ejecutar los comandos bundle desde un sistema CI como Acciones de GitHub o Azure DevOps. En cada solicitud de incorporación de cambios, se ejecuta una buena línea de base:

  1. pytest frente a sus funciones de transformación comprobables mediante pruebas unitarias. Consulte Pruebas unitarias para canalizaciones.
  2. databricks bundle validate --target <env> para detectar errores de configuración.
  3. Opcionalmente, usar un databricks bundle run en un destino temporal para validar las expectativas con datos de ejemplo.

El siguiente flujo de trabajo de Acciones de GitHub se implementa en staging al fusionar a main, usando la federación OpenID Connect (OIDC) en lugar de un token almacenado:

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

Haz que el despliegue en producción dependa de una aprobación manual (por ejemplo, un segundo trabajo que requiera la aprobación de un entorno de GitHub, o una fase independiente en Azure DevOps), para que una persona apruebe explícitamente cada promoción. El trabajo de producción ejecuta databricks bundle deploy --target prod utilizando una entidad de servicio con el alcance del área de trabajo de producción. Para más información, consulta CI/CD sobre Azure Databricks.

Solución de problemas

Cuestión Solución
Error "databricks.yml no encontrado" al ejecutar bundle generate Actualmente, el bundle generate comando no crea automáticamente el archivo de configuración de agrupación (databricks.yml). Debe crear el archivo mediante databricks bundle init o manualmente.
La configuración de canalización existente no coincide con los valores de la canalización generada en YAML. El ID del pipeline no aparece en el archivo YML de configuración del paquete. Si observa alguna otra configuración que falta, puede aplicarlas manualmente.

Sugerencias para el éxito

  • Use siempre el control de versiones. Si no usa carpetas de Git de Databricks, almacene los subdirectorios y archivos del proyecto en git u otro repositorio o sistema de archivos controlado por versiones.
  • Pruebe la canalización en un entorno que no sea de producción (como un entorno de "desarrollo" o "prueba") antes de implementarla en un entorno de producción. Es fácil introducir una configuración incorrecta por accidente.

Recursos adicionales

Para obtener más información sobre el uso de agrupaciones para definir y administrar el procesamiento de datos, consulte:

  • Last updated on