Técnicas de CI/CD com Git e pastas Git do Databricks Git (Repos)

Aprenda técnicas para usar as pastas Git do Databricks em fluxos de trabalho de CI/CD. Ao configurar pastas Git do Databricks no workspace, você pode usar o controle do código-fonte para arquivos de projeto em repositórios Git e integrá-las aos pipelines de engenharia de dados.

A figura a seguir mostra uma visão geral das técnicas e do fluxo de trabalho.

Para obter uma visão geral da CI/CD no Azure Databricks, consulte O que é CI/CD no Azure Databricks?.

Fluxo de desenvolvimento

As pastas Git do Databricks têm pastas no nível do usuário. As pastas de nível de usuário são criadas automaticamente quando os usuários clonam primeiro um repositório remoto. É possível considerar as pastas Git do Databricks em pastas de usuário como "check-outs locais" que são individuais para cada usuário e onde os usuários fazem alterações em seu código.

Em sua pasta de usuário nas pastas Git do Databricks, clone seu repositório remoto. Uma melhor prática é criar um nov branch de recurso ou selecionar um branch criado anteriormente, para seu trabalho, em vez de confirmar e enviar diretamente as alterações para o branch principal. Você pode fazer alterações, confirmar e enviar alterações por push nessa ramificação. Quando estiver pronto para mesclar o código, você poderá fazer isso na interface do usuário das pastas Git.

Requisitos

Este fluxo de trabalho exige que você já tenha configurado sua integração do Git.

Colaborar em pastas Git

O fluxo de trabalho a seguir usa um branch chamado feature-b que se baseia na ramificação principal.

1. Clone seu repositório do Git existente para o workspace do Databricks.
2. Use a interface do usuário das pastas Git para criar uma ramificação de recurso a partir da ramificação principal. Este exemplo usa um recurso de ramificação de feature-b único para simplificar. Você pode criar e usar várias ramificações de recurso para fazer seu trabalho.
3. Faça suas modificações em arquivos e notebooks do Azure Databricks e em outros arquivos no Repo.
4. Faça o commit e o push de suas alterações para o provedor do Git.
5. Os colaboradores já podem clonar o repositório Git em uma pasta de usuário própria.
   1. Trabalhando em uma nova ramificação, um colega de trabalho faz alterações nos notebooks e em outros arquivos na pasta Git.
   2. O colaborador faz o commit e efetua push das alterações para o provedor do Git.
6. Para mesclar alterações de outros branches ou basear novamente o branch feature-b no Databricks, na interface do usuário das pastas Git, use um dos seguintes fluxos de trabalho:
   • Mesclar branches. Se não houver conflito, a mesclagem será enviada para o repositório Git remoto usando git push.
   • Basear novamente em outro branch.
7. Quando estiver pronto para mesclar seu trabalho no repositório Git remoto e na ramificação main, use a interface do usuário de pastas do Git para mesclar as alterações de feature-b. Se preferir, você pode mesclar as alterações diretamente no repositório Git que suporta sua pasta Git.

Fluxo de trabalho de produção

As pastas Git do Databricks fornecem duas opções para executar trabalhos de produção:

• Opção 1: Fornecer uma referência Git remota na definição do trabalho. Por exemplo, executar um notebook específico na ramificação main de um repositório Git.
• Opção 2: Configurar um repositório Git de produção e chamar as APIs do Repos para atualizá-lo programaticamente. Execute trabalhos na pasta Git do Databricks que clona esse repositório remoto. A chamada à API do Repos deve ser a primeira tarefa do trabalho.

Opção 1: Executar trabalhos usando notebooks em um repositório remoto

Simplifique o processo de definição de trabalho e mantenha uma única fonte de verdade executando um trabalho do Azure Databricks usando notebooks localizados em um repositório Git remoto. Essa referência do Git pode ser um commit, tag ou branch do Git e é fornecida por você na definição do trabalho.

Isso ajuda a evitar alterações não intencionais no seu trabalho de produção, como quando um usuário faz edições locais em um repositório de produção ou alterna as ramificações. Também automatiza a etapa de CD, pois você não precisa criar uma pasta Git de produção separada no Databricks, gerenciar permissões para ela e mantê-la atualizada.

Consulte Usar o Git com trabalhos.

Opção 2: Configurar uma pasta Git de produção e automação Git

Nesta opção, você configura uma pasta Git de produção e automação para atualizar a pasta Git na mesclagem.

Etapa 1: configurar pastas de nível superior

O administrador cria pastas de nível superior que não são do usuário. O caso de uso mais comum para essas pastas de nível superior é criar pastas de desenvolvimento, de preparo e de produção que contenham pastas Git do Databricks para as versões ou ramificações apropriadas para desenvolvimento, preparo e produção. Por exemplo, se a sua empresa usar a ramificação main para produção, a pasta Git de "produção" deverá ter a ramificação main verificada nela.

Normalmente, as permissões nessas pastas de nível superior são somente leitura para todos os usuários não administradores no espaço de trabalho. Para essas pastas de nível superior, recomendamos que você forneça apenas entidades de serviço com as permissões PODE EDITAR e PODE GERENCIAR para evitar edições acidentais no código de produção por usuários do workspace.

Etapa 2: Configurar atualizações automatizadas para pastas Git do Databricks com a API de pastas Git

Para manter uma pasta Git no Databricks na versão mais recente, você pode configurar a automação do Git para chamar a API do Repos. Em seu provedor Git, configure a automação que, após cada mesclagem bem-sucedida de uma PR no branch principal, chama o ponto de extremidade da API do Repos na pasta Git apropriada para atualizá-la para a versão mais recente.

Por exemplo, em GitHub isso pode ser obtido com as GitHub Actions. Para obter mais informações, consulte a API do Repos.

Para chamar qualquer API REST do Databricks de dentro de uma célula de notebook do Databricks, primeiro instale o SDK do Databricks com %pip install databricks-sdk --upgrade (para obter as APIs REST mais recentes do Databricks) e, em seguida, importe ApiClient de databricks.sdk.core.

Você também pode executar APIs de SDK do Databricks em um notebook para recuperar as entidades de serviço para seu espaço de trabalho. Aqui está um exemplo usando o Python e o SDK do Databricks para Python.

Você também pode usar ferramentas como curl ou Terraform. Você não pode usar a interface do usuário do Azure Databricks.

Para saber mais sobre entidades de serviço no Azure Databricks, consulte Gerenciar entidades de serviço. Para obter informações sobre entidades de serviço e CI/CD, confira Entidades de serviço para CI/CD. Para obter mais detalhes sobre como usar o SDK do Databricks em um notebook, leia Usar o SDK do Databricks para Python em um notebook do Databricks.

Usar uma entidade de serviço com pastas Git do Databricks

Para executar os fluxos de trabalho mencionados acima com entidades de serviço:

1. Crie uma entidade de serviço com o Azure Databricks.
2. Adicione as credenciais do Git: use o PAT do provedor Git para a entidade de serviço.

Para configurar entidades de serviço e adicionar credenciais do provedor Git:

1. Crie uma entidade de serviço. Confira Executar trabalhos com entidades de serviço.
2. Crie um token do Microsoft Entra ID para uma entidade de serviço.
3. Depois de criar uma entidade de serviço, adicione-a ao workspace do Azure Databricks com a API de Entidades de Serviço.
4. Adicione suas credenciais do provedor do Git ao workspace com o token do Microsoft Entra ID e a API de Credenciais do Git.

Integração do Terraform

Gerencie também pastas Git do Databricks em uma configuração totalmente automatizada usando o Terraform e o databricks_repo:

resource "databricks_repo" "this" {
  url = "https://github.com/user/demo.git"
}

Para usar o Terraform para adicionar credenciais do Git a uma entidade de serviço, adicione a seguinte configuração:

  provider "databricks" {
    # Configuration options
  }

  provider "databricks" {
    alias = "sp"
    host = "https://....cloud.databricks.com"
    token = databricks_obo_token.this.token_value
  }

  resource "databricks_service_principal" "sp" {
    display_name = "service_principal_name_here"
  }

  resource "databricks_obo_token" "this" {
    application_id   = databricks_service_principal.sp.application_id
    comment          = "PAT on behalf of ${databricks_service_principal.sp.display_name}"
    lifetime_seconds = 3600
  }

  resource "databricks_git_credential" "sp" {
    provider = databricks.sp
    depends_on = [databricks_obo_token.this]
    git_username          = "myuser"
    git_provider          = "azureDevOpsServices"
    personal_access_token = "sometoken"
  }

Configurar um pipeline automatizado de CI/CD com pastas Git do Databricks

Aqui está uma automação simples que pode ser executada como uma Ação do GitHub.

Requisitos

• Você criou uma pasta Git em um workspace do Databricks que está rastreando a ramificação de base que está sendo mesclada.
• Você tem um pacote Python que cria os artefatos para colocar em um local DBFS. Seu código deve:
  • Atualizar o repositório associado à sua ramificação preferida (como development) para conter as versões mais recentes de seus notebooks.
  • Compilar todos os artefatos e copiá-los para o caminho da biblioteca.
  • Substituir as últimas versões dos artefatos de compilação para evitar a necessidade de atualizar manualmente as versões dos artefatos em seu trabalho.

Criar um fluxo de trabalho automatizado de CI/CD

1. Configure segredos para que seu código possa acessar o workspace do Databricks. Adicione os seguintes segredos ao repositório do Github:

   • DEPLOYMENT_TARGET_URL: Defina isso como a URL do seu workspace. Não inclua a /?o substring.
   • DEPLOYMENT_TARGET_TOKEN: defina isso como um PAT (Token de Acesso Pessoal) do Databricks. Você pode gerar um PAT do Databricks seguindo as instruções em Autenticação de token de acesso pessoal do Azure Databricks.

2. Navegue até a guia Ações do seu repositório Git e clique no botão Novo fluxo de trabalho. Na parte superior da página, selecione Configure você mesmo um fluxo de trabalho e cole este script:

   

   # This is a basic automation workflow to help you get started with GitHub Actions.
   
   name: CI
   
   # Controls when the workflow will run
   on:
     # Triggers the workflow on push for main and dev branch
     push:
       paths-ignore:
         - .github
       branches:
         # Set your base branch name here
         - your-base-branch-name
   
   # A workflow run is made up of one or more jobs that can run sequentially or in parallel
   jobs:
     # This workflow contains a single job called "deploy"
     deploy:
       # The type of runner that the job will run on
       runs-on: ubuntu-latest
       environment: development
       env:
         DATABRICKS_HOST: ${{ secrets.DEPLOYMENT_TARGET_URL }}
         DATABRICKS_TOKEN:  ${{ secrets.DEPLOYMENT_TARGET_TOKEN }}
         REPO_PATH: /Workspace/Users/someone@example.com/workspace-builder
         DBFS_LIB_PATH: dbfs:/path/to/libraries/
         LATEST_WHEEL_NAME: latest_wheel_name.whl
   
       # Steps represent a sequence of tasks that will be executed as part of the job
       steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@v3
   
       - name: Setup Python
         uses: actions/setup-python@v3
         with:
         # Version range or exact version of a Python version to use, using SemVer's version range syntax.
           python-version: 3.8
   
       # Download the Databricks CLI. See https://github.com/databricks/setup-cli
       - uses: databricks/setup-cli@main
   
       - name: Install mods
         run: |
           pip install pytest setuptools wheel
   
       - name: Extract branch name
         shell: bash
         run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
         id: extract_branch
   
       - name: Update Databricks Git folder
         run: |
           databricks repos update ${{env.REPO_PATH}} --branch "${{ steps.extract_branch.outputs.branch }}"
   
       - name: Build Wheel and send to Databricks DBFS workspace location
         run: |
           cd $GITHUB_WORKSPACE
           python setup.py bdist_wheel
           dbfs cp --overwrite ./dist/* ${{env.DBFS_LIB_PATH}}
           # there is only one wheel file; this line copies it with the original version number in file name and overwrites if that version of wheel exists; it does not affect the other files in the path
           dbfs cp --overwrite ./dist/* ${{env.DBFS_LIB_PATH}}${{env.LATEST_WHEEL_NAME}} # this line copies the wheel file and overwrites the latest version with it
   

3. Atualize os seguintes valores de variáveis de ambiente com os seus próprios valores:

   • DBFS_LIB_PATH: O caminho no DBFS para as bibliotecas (rodas) que você usará nessa automação, que começa com dbfs:. Por exemplo, dbfs:/mnt/myproject/libraries.
   • REPO_PATH: O caminho em seu workspace do Databricks para a pasta Git no qual os notebooks serão atualizados.
   • LATEST_WHEEL_NAME: O nome do último arquivo wheel do Python compilado (.whl). Isso é usado para evitar a atualização manual das versões de roda em seus trabalhos do Databricks. Por exemplo, your_wheel-latest-py3-none-any.whl.

4. Selecione Confirmar alterações... para confirmar o script como um fluxo de trabalho do GitHub Actions. Depois que a pull request desse fluxo de trabalho for mesclada, acesse a guia Ações do repositório Git e confirme se as ações foram bem-sucedidas.