使用 Git 和 Databricks Git 資料夾的 CI/CD 技術 (Repos)

發行項
10/18/2024

了解在 CI/CD 工作流程中使用 Databricks Git 資料夾的技術。藉由在工作區中設定 Databricks Git 資料夾，您可以使用 Git 存放庫中專案檔的原始檔控制，並將整合到資料工程管線中。

下圖顯示技術和工作流程的概觀。

Git 資料夾的 CI/CD 技術概觀。

如需 Azure Databricks 上的 CI/CD 概觀，請參閱什麼是 Azure Databricks 上的 CI/CD？。

開發流程

Databricks Git 資料夾具有使用者層級的資料夾。當使用者第一次複製遠端存放庫時，系統會自動建立使用者層級資料夾。您可以將使用者資料夾中的 Databricks Git 資料夾視為每個使用者的「本機結帳」，以及使用者對其程式碼進行變更的位置。

在 Databricks Git 資料夾中的使用者資料夾中，複製遠端存放庫。最佳做法是建立新功能分支，或為您的工作選取先前建立的分支，而不是直接認可和推送主要分支的變更。您可以在該分支中進行變更、提交和推送變更。當您準備好合併程式代碼時，您可以在 Git 資料夾 UI 中執行此動作。

需求

此工作流程需要您已設定 Git 整合。

注意

Databricks 建議每個開發人員在自己的功能分支上運作。如需如何解決合併衝突的資訊，請參閱解決合併衝突。

在 Git 資料夾中共同作業

以下工作流程使用一個名為 feature-b 的分支，該分支以主分支為基礎。

將現有的 Git 存放庫複製到 Databricks 工作區。
使用 Git 資料夾 UI 從主要分支建立功能分支。此範例會使用單一功能分支 feature-b 來簡化。您可以建立和使用多個功能分支來執行您的工作。
對存放庫中的 Azure Databricks 筆記本和其他檔案進行修改。
認可並推送您的變更至 Git 供應商。
投稿人現在可以將 Git 存放庫複製到自己的使用者資料夾。
1. 在新的分支上，同事會變更 Git 資料夾中的筆記本和其他檔案。
2. 投稿人提交並將其變更推送至 Git 提供者。
若要合併來自其他分支的變更，或重訂基底 Databricks 中的 feature-b 分支，請在 Git 資料夾 UI 中使用下列其中一個工作流程：
- 合併分支。如果沒有衝突，則會使用 git push 將合併推送至遠端 Git 存放庫。
- 以另一個分支重訂基底。
當您準備好將工作合併至遠端 Git 存放庫和 main 分支時，請使用 Git 資料夾 UI 來合併來自 feature-b 的變更。如果您想要的話，您可以改為將變更直接合併至 Git 存放庫，以備份 Git 資料夾。

生產作業工作流程

Databricks Git 資料夾提供兩個選項來執行生產作業：

選項 1：在作業定義中提供遠端 Git 參考。例如，在 Git 存放庫的分支中由 main 執行特定筆記本。
選項 2：設定生產 Git 存放庫，並呼叫 Repos API 以程式設計方式更新。針對複製此遠端存放庫的 Databricks Git 資料夾執行作業。 Repos API 呼叫應該是作業中的第一個工作。

選項 1：使用遠端存放庫中的筆記本執行作業

使用位於遠端 Git 存放庫中的筆記本執行 Azure Databricks 作業，以簡化作業定義程式，並保留單一事實來源。此 Git 參考可以是 Git 提交、標記或分支，並由您在作業定義中提供。

這有助於防止非預期的生產作業變更，例如當使用者在生產存放庫或切換分支中進行本機編輯時。它也會自動執行CD步驟，因為您不需要在 Databricks 中建立個別的生產 Git 資料夾、管理其權限，並讓它保持更新。

請參閱搭配作業使用 Git。

選項 2：設定生產 Git 資料夾和 Git 自動化

在此選項中，您會設定生產 Git 資料夾和自動化，以在合併時更新 Git 資料夾。

步驟 1：設定最上層資料夾

系統管理員會建立非使用者最上層資料夾。這些最上層資料夾最常見的使用案例是建立開發、預備和生產資料夾，其中包含適用於開發、預備和生產之適當版本或分支的 Databricks Git 資料夾。例如，如果您的公司使用 main 分支進行生產，則「生產」Git 資料夾中必須有檢出的 main 分支。

這些最上層資料夾的權限通常是工作區內所有非系統管理員使用者的唯讀權限。針對這類最上層資料夾，我們建議您只提供具有 CAN EDIT 和 CAN MANAGE 權限的服務主體，以避免工作區使用者意外編輯您的生產程序代碼。

最上層 Git 資料夾。

步驟 2：使用 Git 資料夾 API 設定 Databricks Git 資料夾的自動更新

若要在 Databricks 中保留最新版本的 Git 資料夾，您可以設定 Git 自動化來呼叫 Repos API。在您的 Git 提供者中，設定自動化，在將 PR 成功合併到主要分支之後，請在適當的 Git 資料夾中呼叫 Repos API 端點，將它更新為最新版本。

例如，在 GitHub 上，您可以使用 GitHub Actions 來達成此目的。如需詳細資訊，請參閱 Repos API。

若要從 Databricks 筆記本儲存格內呼叫任何 Databricks REST API，請先使用安裝 Databricks SDK 與 %pip install databricks-sdk --upgrade (如需最新的 Databricks REST API)，然後從 databricks.sdk.core 匯入 ApiClient。

注意

如果 %pip install databricks-sdk --upgrade 傳回「找不到套件」的錯誤，則 databricks-sdk 尚未安裝套件。重新執行不帶 --upgrade 標幟的命令：%pip install databricks-sdk。

您也可以從筆記本執行 Databricks SDK API，以擷取工作區的服務主體。以下是使用 Python 和適用於 Python 的 Databricks SDK 的範例。

您也可以使用 curl 或 Terraform 之類的工具。您無法使用 Azure Databricks 使用者介面。

若要了解 Azure Databricks 上服務主體的詳細資訊，請參閱管理服務主體。如需服務主體和 CI/CD 的相關資訊，請參閱 CI/CD 的服務主體。如需從筆記本使用 Databricks SDK 的詳細資訊，請參閱從 Databricks 筆記本中使用適用於 Python 的 Databricks SDK。

搭配 Databricks Git 資料夾使用服務主體

若要使用服務主體執行上述工作流程：

使用 Azure Databricks 建立服務主體。
新增 Git 認證：為您的服務主體使用 Git 提供者 PAT。

若要設定服務主體，然後新增 Git 提供者認證：

建立服務主體。請參閱使用服務主體執行作業。
為服務主體建立 Microsoft Entra ID 權杖。
建立服務主體之後，您可以使用服務主體 API 將它新增至 Azure Databricks 工作區。
使用您的 Microsoft Entra ID 權杖和 Git 認證 API，將 Git 提供者認證新增至工作區。

Terraform 整合

您也可以使用 Terraform 和 databricks_repo，在完全自動化的設定中管理 Databricks Git 資料夾：

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

若要使用 Terraform 將 Git 認證新增至服務主體，請新增下列設定：

  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"
  }

使用 Databricks Git 資料夾設定自動化 CI/CD 管線

以下是一個簡單的自動化，可以當做 GitHub Action 來執行。

需求

您已在 Databricks 工作區中建立 Git 資料夾，以追蹤要合併的基底分支。
您有一個 Python 套件，其會建立要放置於 DBFS 位置的成品。您的程式碼必須：
- 更新與您慣用分支相關聯的存放庫 (例如 development)，以包含最新版的筆記本。
- 建置任何成品，並將其複製到連結庫路徑。
- 取代最後一個組建成品版本，以避免必須手動更新作業中的成品版本。

建立自動化 CI/CD 工作流程

設定秘密，讓您的程式代碼可以存取 Databricks 工作區。將下列秘密新增至 Github 存放庫：
- DEPLOYMENT_TARGET_URL：將此設定為您的工作區 URL。請勿包含 /?o 子字串。
- DEPLOYMENT_TARGET_TOKEN：將此設定為 Databricks 個人存取令牌（PAT）。您可以遵循 Azure Databricks 個人存取令牌驗證中的指示來產生 Databricks PAT。

瀏覽至 Git 存放庫的動作索引標籤，然後按兩下新增工作流程按鈕。在頁面頂端，選取自行設定工作流程，並貼上此指令碼：

GitHub Actions UI 中的「自行設定工作流程」連結

# 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

使用您自己的值更新下列環境變數值：
- DBFS_LIB_PATH：您將在此自動化中使用的 DBFS 連結庫路徑 (輪子)，其開頭為 dbfs:。例如，dbfs:/mnt/myproject/libraries。
- REPO_PATH：Databricks 工作區中要更新筆記本的 Git 資料夾路徑。
- LATEST_WHEEL_NAME：上次編譯 Python 轉輪檔案的名稱 (.whl)。這可用來避免在 Databricks 作業中手動更新轉輪版本。例如： your_wheel-latest-py3-none-any.whl 。
選取提交變更，將指令碼提交為 GitHub Actions 工作流程。合併此工作流程的提取要求之後，請移至 Git 存放庫的動作索引標籤，並確認動作是否成功。

共用方式為