Git と Databricks Git フォルダー (Repos) を使用した CI/CD 手法

[アーティクル]
04/24/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 統合を設定してある必要があります。

Note

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 プロバイダーで変更をマージすることもできます。

運用ジョブのワークフロー

Databricks Git フォルダーには、運用ジョブを実行するための 2 つのオプションがあります。

オプション 1: ジョブ定義にリモート Git 参照を指定します。たとえば、Git リポジトリの main ブランチにある特定のノートブックを実行します。
オプション 2: 運用 Git リポジトリを設定し、Repos API を呼び出してプログラムで更新します。このリモートリポジトリをクローンする Databricks Git フォルダーに対してジョブを実行します。 Repos API 呼び出しは、ジョブ内の最初のタスクにする必要があります。

オプション 1: リモートリポジトリにあるノートブックを使用してジョブを実行する

リモート Git リポジトリにあるノートブックを使用して Azure Databricks ジョブを実行することで、ジョブ定義プロセスを簡略化し、1 つの信頼できるソースを維持します。この Git 参照は、Git コミット、タグ、またはブランチにすることができ、ジョブ定義で提供できます。

これにより、ユーザーが運用リポジトリでローカル編集を行ったり、ブランチを切り替えたりする場合など、運用ジョブに対する意図しない変更を防ぐことに役に立ちます。 Databricks で別の運用 Git フォルダーを作成し、そのアクセス許可を管理し、更新を維持する必要がないので、CD ステップも自動化されます。

「Azure Databricks ジョブにおけるバージョン管理されたソースコードの使用」を参照してください。

オプション 2: 運用 Git フォルダーと Git 自動化を設定する

このオプションでは、マージ時に Git フォルダーを更新するように運用 Git フォルダーと自動化を設定します。

ステップ 1: 最上位のフォルダーを設定する

管理者は、ユーザーのものではない最上位のフォルダーを作成します。これらの最上位フォルダーの最も一般的なユースケースは、開発、ステージング、運用のための適切なバージョンまたはブランチに対する Databricks Git フォルダーを含む開発、ステージング、運用フォルダーを作成することです。たとえば、会社が運用のために main ブランチを使っている場合、"運用" Git フォルダーにはチェックアウト先となる main ブランチが必要です。

通常、このような最上位フォルダーに対するアクセス許可は、ワークスペース内のすべての管理者以外のユーザーに対して読み取り専用です。このような最上位フォルダーの場合は、ワークスペースユーザーによる運用コードの誤った編集を回避するために、サービスプリンシパルにのみ編集可能および管理可能のアクセス許可を指定することをお勧めします。

最上位の Git フォルダー。

手順 2: Git フォルダー API を使用して Databricks Git フォルダーへの自動更新を設定する

Databricks の Git フォルダーを最新バージョンに保つため、Repos API を呼び出すように Git 自動化を設定できます。メインブランチへの PR のマージが正常に行われるたびに、適切な Git フォルダーで Repos API エンドポイントを呼び出して、それを最新バージョンに更新するように、Git プロバイダーで自動化を設定します。

たとえば、GitHub では、GitHub Actions を使用してこれを実現できます。詳しくは、Repos API に関するページをご覧ください。

Databricks ノートブックセル内から任意の Databricks REST API を呼び出すには、最初に Databricks SDK を %pip install databricks-sdk --upgrade (最新の Databricks REST API 用) でインストールし、その後 databricks.sdk.core から ApiClient をインポートします。

Note

%pip install databricks-sdk --upgrade が "パッケージが見つかりませんでした" というエラーを返した場合、databricks-sdk パッケージは過去にインストールされていません。 --upgrade フラグを指定せずにコマンドを再実行します: %pip install databricks-sdk。

また、ノートブックから Databricks SDK API を実行して、ワークスペースのサービスプリンシパルを取得することもできます。 Python と Databricks SDK for Python の使用例を次に示します。

また、curl、Postman、Terraform などのツールを使用することもできます。 Azure Databricks ユーザーインターフェイスを使用することはできません。

Azure Databricks のサービスプリンシパルの詳細については、「サービスプリンシパルの管理」を参照してください。サービスプリンシパルと CI/CD の詳細については、「CI/CD のサービスプリンシパル」を参照してください。ノートブックから Databricks SDK を使用することに関する詳細については、「Databricks ノートブックから Databricks SDK for Python を使用する」を参照してください。

Databricks Git フォルダーでサービスプリンシパルを使用する

サービスプリンシパルを使用して上記のワークフローを実行するには:

Azure Databricks でサービスプリンシパルを作成します。
Git 資格情報を追加します。サービスプリンシパルに Git プロバイダー PAT を使用します。

サービスプリンシパルを設定して、Git プロバイダーの資格情報を追加するには、次の操作を行います。

サービスプリンシパルを作成する。 Azure サービスプリンシパルを使用したジョブの実行に関する記事を参照してください。
サービスプリンシパルの Microsoft Entra ID トークンを作成します。
サービスプリンシパルを作成したら、Service Principals API を使用してそれを Azure Databricks ワークスペースに追加します。
Microsoft Entra ID トークンと Git Credentials 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 アクションとして実行できる簡単な自動化を紹介します。

要件

マージ先のベースブランチを追跡する Databricks ワークスペースに Git フォルダーを作成してあります。
Python パッケージは、DBFS の場所に配置する成果物を作成します。コードは次のようにする必要があります。
- 優先ブランチ (development など) に関連するリポジトリを更新して、ノートブックの最新バージョンを含めます。
- 成果物をビルドし、ライブラリパスにコピーします。
- ビルド成果物の最終バージョンを置き換えることで、ジョブ内で成果物のバージョンを手動で更新する必要がなくなります。

手順

Note

手順 1 は、Git リポジトリの管理者が行う必要があります。

コードで Databricks ワークスペースにアクセスできるようにシークレットを設定します。 Github リポジトリに次のシークレットを追加します。
- DEPLOYMENT_TARGET_URL: これは、ワークスペース URL に設定しますが、/?o 部分文字列は含めないでください。
- DEPLOYMENT_TARGET_TOKEN: Databricks 個人用アクセストークン (PAT) の値を指定します。 Databricks PAT は、「リモートリポジトリを Azure Databricks に接続する Git 資格情報を構成する」の手順に従って生成できます。

Git リポジトリの [アクション] タブに移動し、[新しいワークフロー] ボタンをクリックします。ページの上部にある [set up a workflow yourself] (自分でワークフローを設定する) を選択し、次のスクリプトに貼り付けます。

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:
      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
      env:
        DBFS_LIB_PATH: dbfs:/path/to/libraries/
        REPO_PATH: /Repos/path/here
        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@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
        # Version range or exact version of a Python version to use, using SemVer's version range syntax.
          python-version: 3.8

      - name: Install mods
        run: |
          pip install databricks-cli
          pip install pytest setuptools wheel

      - name: Configure CLI
        run: |
          echo "${{ secrets.DEPLOYMENT_TARGET_URL }} ${{ secrets.DEPLOYMENT_TARGET_TOKEN }}" | databricks configure --token

      - 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 --path ${{env.REPO_PATH}} --branch "${{ steps.extract_branch.outputs.branch }}"

      - name: Build Wheel and send to Databricks workspace DBFS 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: ノートブックが更新される Git フォルダーへの Databricks ワークスペース内のパス。たとえば、/Repos/Develop のようにします。
- LATEST_WHEEL_NAME: 最後にコンパイルされた Python wheel ファイル (.whl) の名前。これは、Databricks ジョブでホイールバージョンを手動で更新するのを回避するために使用します。たとえば、your_wheel-latest-py3-none-any.whl のようにします。
[変更点のコミット...] を選択して、スクリプトを GitHub Actions ワークフローとしてコミットします。このワークフローの pull request がマージされたら、Git リポジトリの [アクション] タブに移動して、アクションが成功したことを確認します。

Git と Databricks Git フォルダー (Repos) を使用した CI/CD 手法

開発フロー

要件

Git フォルダーで共同作業する

運用ジョブのワークフロー

オプション 1: リモート リポジトリにあるノートブックを使用してジョブを実行する

オプション 2: 運用 Git フォルダーと Git 自動化を設定する

ステップ 1: 最上位のフォルダーを設定する

手順 2: Git フォルダー API を使用して Databricks Git フォルダーへの自動更新を設定する

Databricks Git フォルダーでサービス プリンシパルを使用する

Terraform の統合

Databricks Git フォルダーを使用して自動 CI/CD パイプラインを構成する

要件

手順

その他のリソース

オプション 1: リモートリポジトリにあるノートブックを使用してジョブを実行する

Databricks Git フォルダーでサービスプリンシパルを使用する