CI/CD para aplicaciones de Databricks con Acciones de GitHub

En esta página se explica cómo automatizar la implementación de una aplicación de Databricks desde GitHub mediante Acciones de GitHub y Declarative Automation Bundles. Abarca la federación de identidades de carga de trabajo, el flujo de trabajo YAML y una comprobación de estado que confirma que la aplicación está sirviendo el código más reciente después de cada implementación.

Para obtener instrucciones de Acciones de GitHub genéricas para trabajos y canalizaciones de Azure Databricks, consulte Acciones de GitHub. Para la configuración de la federación de identidades de carga de trabajo, consulte Enable workload identity federation for Acciones de GitHub.

Requirements

Paso 1. Configuración de la federación de identidades de carga de trabajo

La federación de identidades de carga de trabajo permite que el ejecutor de Acciones de GitHub se autentique con Azure Databricks mediante un token OIDC de corta duración en lugar de almacenar credenciales en el repositorio.

Siga los pasos de Habilitar la federación de identidades de carga de trabajo para Acciones de GitHub para crear una directiva de federación de Acciones de GitHub en su entidad de servicio. Tome nota del identificador de aplicación (UUID) de la entidad de servicio y de la URL de su área de trabajo. Necesitas las dos como variables en el flujo de trabajo.

A continuación, conceda a la entidad de servicio CAN MANAGE permiso sobre la aplicación o permiso en el área de trabajo para crear aplicaciones si la aplicación aún no existe. Consulte Configuración de permisos para una aplicación de Databricks.

Paso 2. Configuración del repositorio de GitHub

En el repositorio de GitHub, cree un entorno de implementación para almacenar las variables de conexión del área de trabajo. El uso de un entorno también le permite requerir aprobación manual antes de que se ejecuten las implementaciones.

  1. En Entornos de configuración>, cree un entorno denominadoprod (o cualquier nombre al que haga referencia el flujo de trabajo).
  2. En Variables de entorno, agregue lo siguiente:
Variable Value
DATABRICKS_HOST La dirección URL del área de trabajo, por ejemplo, https://my-workspace.cloud.databricks.com
DATABRICKS_CLIENT_ID El identificador de aplicación de la entidad de servicio del paso 1

Ninguno de los valores es una credencial. La política de federación de la entidad de seguridad de servicio controla quién puede autenticarse como tal, por lo que el identificador de cliente por sí solo no concede acceso. No necesitas un secreto del cliente.

Paso 3. Configure su paquete para despliegues de producción

En databricks.yml, declare un espacio de trabajo host explícito y root_path en el destino prod. Esto garantiza que la agrupación se implemente en la misma ubicación en cada ejecución. La validación en modo de producción requiere ambos campos, a menos que run_as se haya configurado como un principal de servicio. Consulte Modos de implementación de paquetes de automatización declarativos.

targets:
  prod:
    mode: production
    workspace:
      host: https://my-workspace.cloud.databricks.com
      root_path: /Workspace/Users/<service-principal-or-owner>/.bundle/${bundle.name}/${bundle.target}
    resources:
      apps:
        my_app:
          name: my-app
          source_code_path: ./app

Reemplace <service-principal-or-owner> por el usuario del área de trabajo propietario de los artefactos del paquete, normalmente el identificador de aplicación de la entidad de servicio.

Reemplace por ./app la ruta de acceso al código fuente de la aplicación en relación con databricks.yml. El source_code_path campo es necesario cuando el código de la aplicación reside en el mismo repositorio que la agrupación. Si el código de la aplicación reside en un repositorio independiente, use git_source en su lugar. Consulte aplicación.

Paso 4. Adición del flujo de trabajo de implementación

Agregue .github/workflows/deploy.yml al repositorio:

name: Deploy to Databricks Apps

on:
  workflow_dispatch:
  # Uncomment to deploy on every push to main once the workflow is validated.
  # push:
  #   branches: [main]

permissions:
  id-token: write # required for OIDC federation
  contents: read

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: prod
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}
    steps:
      - uses: actions/checkout@v4

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

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

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

      - name: Start or restart app
        run: databricks bundle run my_app --target prod

Reemplace my_app en el último paso por la clave de recurso que databricks.yml usa en resources.apps.

El ejecutor necesita el permiso id-token: write para solicitar un token de OIDC. La databricks/setup-cli acción lee DATABRICKS_AUTH_TYPE=github-oidc y controla la autenticación automáticamente.

Advertencia

databricks bundle deploy carga el código fuente y actualiza los recursos, pero no reinicia el proceso de la aplicación. Si omites el paso final databricks bundle run, el despliegue se completa correctamente en CI mientras la aplicación sigue sirviendo el código anterior. Ejecute siempre el recurso de agrupación después de la implementación.

Paso 5. Espere a que la aplicación esté en buen estado

Databricks recomienda agregar un paso de sondeo de estado después de la implementación. databricks bundle run se cierra tan pronto como señale la aplicación para iniciarse, pero es posible que la aplicación aún no se esté ejecutando. Todavía se puede producir un error durante el inicio debido a problemas como dependencias que faltan, una variable de entorno que falta o un conflicto de puerto. Añadir un paso de sondeo garantiza que un arranque fallido también haga fallar el flujo de trabajo:

- name: Wait for app to be running
  env:
    APP_NAME: my-app
  run: |
    for i in $(seq 1 20); do
      STATE=$(databricks apps get "$APP_NAME" --output json | jq -r '.app_status.state')
      echo "Attempt $i/20: state=$STATE"
      if [ "$STATE" = "RUNNING" ]; then
        exit 0
      fi
      sleep 15
    done
    echo "App did not reach RUNNING state within 5 minutes" >&2
    exit 1

Establezca APP_NAME con el valor que su databricks.yml declara en resources.apps.<key>.name, no con la clave de recurso del paquete.

Control de una aplicación existente

Los nombres de aplicación son únicos en el área de trabajo. El paso bundle deploy falla con An app with the same name already exists cuando otro paquete (o una aplicación creada manualmente) ya es propietario de una aplicación con ese nombre. Vincula el paquete a la aplicación existente en lugar de recrearla.

Ejecute esto una vez localmente para asociar la agrupación a la aplicación existente:

databricks bundle deployment bind my_app <existing-app-name> --target prod --auto-approve

A continuación, vuelva a ejecutar el flujo de trabajo. Las implementaciones posteriores reutilizan el enlace.

Si la aplicación existente tiene configuración del servidor (como budget_policy_id) que no está en su databricks.yml, cópiela en el archivo de paquete antes de volver a implementarla. Los errores de coincidencia aparecen como un error "resultado incoherente" de Terraform durante el paso de implementación del lote.

Elección de un desencadenador

Comience con workflow_dispatch para que la primera implementación sea manual. Una vez que unas cuantas ejecuciones se completen correctamente, añade push: branches: [main] para desplegar en cada fusión.

Como medida de seguridad adicional, configure el entorno prod con revisores obligatorios en Configuración>Entornos>prod>Reglas de protección de despliegue. Cada ejecución de flujo de trabajo espera un aprobador antes de que se inicie el trabajo de implementación.

Pasos siguientes

  • Last updated on