CI/CD para aplicações da Databricks com GitHub Actions

Esta página explica como automatizar a implantação de um aplicativo do Databricks a partir do GitHub usando o GitHub Actions e Pacotes de Automação Declarativa. Abrange a federação de identidade de carga de trabalho, o arquivo YAML do fluxo de trabalho e uma verificação de integridade que confirma que o aplicativo está executando a versão mais recente do código após cada implantação.

Para obter orientações gerais sobre o GitHub Actions para trabalhos e pipelines do Azure Databricks, consulte GitHub Actions. Para a configuração da federação de identidade de carga de trabalho, consulte Ativar a federação de identidade de carga de trabalho para o GitHub Actions.

Requirements

Etapa 1. Configurar a federação de identidade de carga de trabalho

A federação de identidade de carga de trabalho permite que o GitHub Actions executor se autentique com Azure Databricks usando um token OIDC de curta duração em vez de armazenar credenciais em seu repositório.

Siga as etapas em Enable workload identity federation for GitHub Actions para criar uma política de federação do GitHub Actions na sua entidade de serviço. Anote o ID do aplicativo da entidade de serviço (UUID) e a URL do seu espaço de trabalho. Você precisa de ambos como variáveis no fluxo de trabalho.

Em seguida, conceda à entidade de serviço CAN MANAGE permissão no aplicativo ou permissão no espaço de trabalho para criar aplicativos, se o aplicativo ainda não existir. Consulte Configurar permissões para um aplicativo do Databricks.

Etapa 2. Configurar o repositório GitHub

No repositório GitHub, crie um ambiente de implantação para armazenar as variáveis de conexão do workspace. O uso de um ambiente também permite que você exija aprovação manual antes da execução das implantações.

  1. EmAmbientes de Configurações>, crie um ambiente chamado prod (ou qualquer nome que seu fluxo de trabalho referencia).
  2. Para variáveis de ambiente, adicione o seguinte:
Variable Value
DATABRICKS_HOST Sua URL do workspace, por exemplo https://my-workspace.cloud.databricks.com
DATABRICKS_CLIENT_ID O ID do aplicativo da entidade de serviço da Etapa 1

Nenhum dos valores é uma credencial. A política de federação do principal de serviço controla quem pode se autenticar como ele; portanto, o ID do cliente, por si só, não concede acesso. Você não precisa de um segredo do cliente.

Etapa 3. Configure seu bundle para implantação em produção

Em databricks.yml, declare um workspace host explícito e root_path no seu destino prod. Isso garante que o pacote seja implantado no mesmo local em cada execução. A validação em modo de produção requer ambos os campos, a menos que run_as seja definido como uma entidade de serviço. Consulte os modos de implantação de Pacotes de Automação Declarativa.

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

Substitua <service-principal-or-owner> pelo usuário do workspace que é proprietário dos artefatos do bundle, normalmente o ID do aplicativo do service principal.

Substitua ./app pelo caminho para o código-fonte do aplicativo relativo a databricks.yml. O source_code_path campo é necessário quando o código do aplicativo reside no mesmo repositório que o pacote. Se o código do aplicativo estiver em um repositório separado, use git_source em vez disso. Confira aplicativo.

Etapa 4. Adicionar o fluxo de trabalho de implantação

Adicione .github/workflows/deploy.yml ao repositório:

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

Substitua my_app na última etapa pela chave de recurso que seu databricks.yml usa em resources.apps.

O executor precisa da permissão id-token: write para solicitar um token OIDC. A databricks/setup-cli ação lê DATABRICKS_AUTH_TYPE=github-oidc e manipula a autenticação automaticamente.

Warning

databricks bundle deploy carrega o código-fonte e atualiza os recursos, mas não reinicia o processo do aplicativo. Se você ignorar a etapa final databricks bundle run, o deploy passará na CI enquanto o aplicativo continuará executando a versão anterior do código. Sempre execute o recurso de pacote após a implantação.

Etapa 5. Aguarde até que o aplicativo esteja saudável

O Databricks recomenda adicionar uma etapa de sondagem de status após a implantação. databricks bundle run sai assim que sinaliza o aplicativo para iniciar, mas o aplicativo pode não estar em execução ainda. Ele ainda pode falhar durante a inicialização devido a problemas como dependências ausentes, uma variável de ambiente ausente ou um conflito de porta. Adicionar uma etapa de verificação garante que uma falha na inicialização também faça o fluxo de trabalho falhar:

- 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

Defina APP_NAME com o valor que seu databricks.yml declara em resources.apps.<key>.name, não com a chave de recurso do pacote.

Manipulando um aplicativo existente

Os nomes dos aplicativos são exclusivos em todo o espaço de trabalho. A etapa bundle deploy falha com An app with the same name already exists quando outro pacote (ou um aplicativo criado manualmente) já é proprietário de um aplicativo com esse nome. Associe seu pacote ao aplicativo existente em vez de recriá-lo.

Execute isso uma vez localmente para anexar o pacote ao aplicativo existente:

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

Em seguida, execute novamente o fluxo de trabalho. As implantações subsequentes reutilizam a associação.

Se o aplicativo existente tiver a configuração do lado do servidor (como budget_policy_id) que não está no seu databricks.yml, copie-o no arquivo de pacote antes de implantar novamente. As incompatibilidades aparecem como um erro de "resultado inconsistente" do Terraform durante a etapa de implantação do pacote.

Escolhendo um acionador

Comece com workflow_dispatch para que a primeira implantação seja manual. Após algumas execuções bem-sucedidas, adicione push: branches: [main] para implantar a cada mesclagem.

Para uma camada adicional de segurança, configure o ambiente prod com revisores obrigatórios em Configurações>Ambientes>prod>Regras de proteção de implantação. Cada execução de fluxo de trabalho aguarda um aprovador antes do início do trabalho de implantação.

Próximas Etapas 

  • Last updated on