Uso de Git con trabajos de Lakeflow

Las tareas de trabajo pueden consultar el código fuente directamente desde un repositorio de Git remoto.

Los siguientes tipos de tareas admiten repositorios de Git remotos:

  • Blocs de notas
  • scripts de Python
  • Archivos SQL
  • proyectos de herramienta de construcción de datos (dbt)

Todas las tareas de un trabajo deben hacer referencia a la misma confirmación en el repositorio remoto. Cuando se inicia una ejecución de trabajo, Azure Databricks toma una instantánea de la rama o commit especificados, para que todas las tareas que se ejecuten en esa ejecución usen la misma versión del código.

Al ver el historial de ejecución de una tarea que ejecuta código almacenado en un repositorio de Git remoto, el panel Detalles de ejecución de tareas incluye detalles de Git, incluido el SHA de confirmación asociado a la ejecución. Para obtener más información, consulte Visualización del historial de ejecución de tareas.

Nota:

Las tareas configuradas para usar un repositorio de Git remoto no pueden escribir en archivos del área de trabajo. Estas tareas deben escribir datos temporales en el almacenamiento efímero conectado al nodo del controlador y los datos persistentes en un volumen o tabla.

Origen del repositorio Git vs. carpetas Git

En esta página se describen las tareas que pueden extraer código fuente directamente desde un repositorio de Git remoto. Las áreas de trabajo también admiten una característica denominada carpetas de Git, donde una carpeta del área de trabajo se sincroniza con un repositorio de Git. Una tarea puede usar una carpeta de Git como origen. Sin embargo, debe administrar la sincronización con el repositorio. El uso de un repositorio Git remoto, como se describe aquí, extrae automáticamente el nuevo origen, si está disponible, durante la ejecución del trabajo.

Azure Databricks recomienda hacer referencia a las rutas de acceso del área de trabajo en carpetas de Git solo para la iteración rápida y las pruebas durante el desarrollo. En el caso de los trabajos de ensayo y producción, configure tareas para hacer referencia a un repositorio de Git remoto en su lugar.

Configura un proveedor Git para un trabajo

La interfaz de usuario de trabajos tiene un cuadro de diálogo para configurar un repositorio de Git remoto. Este cuadro de diálogo es accesible desde el panel Detalles del trabajo en el encabezado Git o en cualquier tarea configurada para usar un proveedor de Git. Para acceder al cuadro de diálogo, haga clic en Agregar configuración de Git en el panel Detalles del trabajo .

En el cuadro de diálogo Git (con la etiqueta Información de Git si se tiene acceso durante la configuración de la tarea), escriba los siguientes detalles:

  • La dirección URL del repositorio de Git.
  • Seleccione el proveedor de Git en la lista desplegable.
  • En el campo de referencia de Git, escriba el identificador de una rama, etiqueta o confirmación que corresponda a la versión del código fuente que desea ejecutar.
  • Seleccione rama, etiqueta o confirmación en la lista desplegable.

Debe especificar solo una de las siguientes opciones:

  • rama: El nombre de la rama, por ejemplo, main.
  • etiqueta: El nombre de la etiqueta, por ejemplo, release-1.0.0.
  • commit: El hash de un commit específico, por ejemplo, e0056d01.

Nota:

Es posible que el cuadro de diálogo le pida lo siguiente: Faltan credenciales de Git para esta cuenta. Agregue credenciales. Debe configurar un repositorio Git remoto antes de usarlo como referencia. Consulte Configuración de la integración de Git para carpetas de Git.

Ejecutar un trabajo Git como rol

Si tu espacio de trabajo utiliza control de acceso basado en roles (RBAC), puedes establecer la identidad Run as de un trabajo en un grupo (rol). A continuación, el trabajo clona su repositorio de Git mediante la credencial de Git del rol, por lo que un administrador debe configurar primero esa credencial o el trabajo no se puede clonar. Para establecer el Ejecutar como de un trabajo en un grupo, consulta Establecer Ejecutar como en un grupo.

Para corregir un trabajo que falla debido a un problema de código, use uno de los métodos de edición en el repositorio y la rama del trabajo. Asume el rol para reproducir y solucionar el problema con los datos del rol, confirma la corrección y, a continuación, vuelve a ejecutar el trabajo.

Sparse checkout para repositorios grandes

En el caso de repositorios de gran tamaño, se puede utilizar la extracción selectiva para importar solo directorios específicos en lugar de todo el repositorio. La extracción selectiva reduce el tiempo de extracción y el consumo de recursos por cada ejecución de trabajo.

Sin embargo, la configuración incorrecta puede provocar la fragmentación de la memoria caché, lo que degrada los tiempos de ejecución en todo el área de trabajo. En esta sección se describen las ventajas e inconvenientes y los problemas que pueden surgir al utilizar la descarga selectiva.

Cómo Azure Databricks almacena en caché los checkouts de repositorios

Azure Databricks almacena en caché cada extracción de Git en función de cuatro valores:

  • Workspace
  • Dirección URL del repositorio
  • Hash de confirmación exacto
  • Huella digital del patrón de descarga selectiva (el conjunto exacto de rutas de carpetas)

Cualquier ejecución de trabajo que coincida con los cuatro criterios reutiliza una entrada de caché, que sigue siendo válida durante hasta una semana. Por ejemplo, si tiene tres trabajos diferentes y todos tienen los mismos criterios, usan la misma memoria caché en el repositorio hasta que haya una nueva confirmación (o después de 1 semana).

Cada patrón único de descarga selectiva crea una huella digital independiente y, por lo tanto, una entrada de caché independiente. Si cada 20 usuarios agregan una carpeta personalizada a su patrón, el sistema crea 20 claves de caché distintas e importa el árbol de carpetas compartidas 20 veces, multiplicando la carga en el área de trabajo. Crear un único patrón de descarga dispersa que incluya las 20 carpetas (por ejemplo, una carpeta principal) permite que una única caché funcione con mayor frecuencia y ofrezca un mejor rendimiento en tus trabajos. La contrapartida es un mayor número de archivos en tu descarga.

Decida si usar sparse checkout

Activa la descarga dispersa solo si tu caso de uso cumple ambos criterios siguientes:

  • Tamaño: Tu repositorio es grande (por ejemplo, supera los 2.500 archivos).
  • Segmentación estable: La rama de destino se actualiza con poca frecuencia (por ejemplo, aproximadamente un commit por hora o menos). Evita las ramas que cambian rápidamente debido a flujos de trabajo automatizados de CI/CD.

Si utilizas el checkout disperso, tu organización también debería adoptar una o ambas de las siguientes estrategias de patrones:

  • Estandarización: Utiliza tres o menos patrones de checkout compartidos en toda la organización para maximizar los aciertos de caché.
  • Microsegmentación: Estructura patrones para que cada uno apunte a un pequeño número de archivos. Para obtener el mejor rendimiento, apunte a menos de 200 archivos.

Esto puede ayudar a minimizar la tasa de importación.

Calcula tu tasa de importación

Antes de habilitar el checkout disperso, calcule la tasa de importación de archivos por hora proyectada. Los límites se aplican en el nivel de área de trabajo en todos los trabajos y usuarios.

Archivos por hora = Ejecuciones de trabajos por hora × Tasa de fallos de caché × Archivos importados por fallo

Factor Lo que lo impulsa
Ejecuciones de trabajos por hora Frecuencia de desencadenamiento en todos los usuarios
Tasa de errores de caché Frecuencia de confirmaciones en la rama de destino y número de patrones dispersos únicos
Archivos importados por error Tamaño total del repositorio o tamaño del subconjunto del checkout disperso

Ejemplo: 180 corridas/hora × 10% de fallos × 6.000 archivos/fallo = 108.000 archivos/hora

Compare el resultado con estos umbrales:

Archivos importados por hora Impacto esperado del área de trabajo
Por debajo de 150 000 Operación normal
150.000 – 300.000 Rendimiento degradado. Algunos trabajos pueden experimentar retrasos o errores.
Encima de 300 000 Los trabajos no se completan de forma confiable.

Mejores prácticas

Estandarizar patrones

  • Haz: Publica tres o menos patrones dispersos aprobados por repositorio. Los patrones compartidos consolidan la carga y maximizan los aciertos de caché.
  • No permita patrones personalizados por equipo. Incluso una carpeta adicional crea una nueva entrada de caché y desencadena una nueva importación completa.

Administra la rotación de confirmaciones

  • Hacer: Apunta los trabajos a una rama de lanzamiento estable. Batch se integra en ventanas de lanzamiento programadas para que varias ejecuciones compartan el mismo commit en caché.
  • No lo hagas: Usa checkouts dispersos con ramas que se actualizan con frecuencia como main. Dado que la memoria caché se basa en el hash de confirmación exacto, cada nueva confirmación invalida la memoria caché y provoca una nueva importación completa para cada ejecución de trabajo.

Administración de la carga

  • Haz: Eliminar grandes binarios, artefactos generados y archivos de datos del control de versiones para reducir incondicionalmente el tamaño del repositorio.
  • No: no deje trabajos redundantes ejecutándose con alta frecuencia. Reduce la frecuencia de activación de las tareas que no requieran una ejecución continua, escalona los horarios o consolida las tareas que compartan la misma copia de código.

Gestionar el churn de commit con una rama de release

Cuando los trabajos apuntan a una rama rápida como main, el hash de commit cambia con frecuencia, causando fallos en la caché en casi todas las ejecuciones. El uso de una rama de versión dedicada que se actualiza según una programación fija mejora las tasas de aciertos de caché.

Al dirigir todas las tareas a una rama de lanzamiento por horas, todas las ejecuciones dentro de esa hora se resuelven con el mismo hash de confirmación y comparten la misma entrada de caché.

Para configurar una rama de versión:

  1. Cree una rama de larga duración (por ejemplo, release-candidate) en el repositorio de Git.
  2. Automatiza la actualización de esta rama para que coincida con main según un horario fijo, como al comienzo de cada hora.
  3. Configure los trabajos respaldados por Git para usar release-candidate como su referencia de Git de destino.

Revise estos inconvenientes antes de implementar:

Consideración Descripción
Retraso en las confirmaciones Los trabajos se ejecutan con código que puede tener hasta una hora de retraso respecto a main. Esto es aceptable para la mayoría de las cargas de trabajo por lotes, pero puede no ser adecuado para trabajos que requieran la última confirmación.
Ventana de fallo Si genera un error el trabajo de corte de la rama de lanzamiento, la rama no se actualiza para esa hora y los trabajos continúan ejecutándose con la confirmación anterior. Databricks recomienda configurar alertas para la tarea de corte.

Ejemplo: automatización con Acciones de GitHub

El siguiente flujo de trabajo de Acciones de GitHub automatiza un corte de la rama de lanzamiento cada hora.

Paso 1: Haz commit de un archivo .github/workflows/cut-release-branch.yml en tu repositorio:

name: Cut Hourly Release Candidate

on:
  schedule:
    - cron: '0 * * * *'
  workflow_dispatch:

jobs:
  update-branch:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout main branch
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0

      - name: Update release-candidate branch
        run: |
          git push origin HEAD:release-candidate --force

Paso 2: Activa manualmente la acción de GitHub para verificar que la release-candidate rama está creada.

Paso 3: Actualiza tus trabajos existentes para usar release-candidate como referencia de Git de destino.

Activa sparse checkout usando la API de Jobs

Para habilitar la descarga selectiva, incluye un bloque sparse_checkout dentro de git_source al crear o actualizar un trabajo:

{
  "git_source": {
    "git_url": "https://github.com/example/my-repo",
    "git_provider": "gitHub",
    "git_branch": "release-candidate",
    "sparse_checkout": {
      "patterns": ["src/models", "src/utils"]
    }
  }
}

Cada cadena de patterns es una ruta de acceso de directorio relativa a la raíz del repositorio. Todos los archivos de cada directorio especificado se incluyen en la descarga.