パイプラインをバンドルプロジェクトに変換する
既存のパイプラインを宣言型オートメーションバンドル プロジェクトに変換できます。バンドルを使用すると、Databricksのデータ処理設定を単一のソース管理されたYAMLファイルで定義および管理できます。これにより、メンテナンスが容易になり、ターゲット環境への自動デプロイが可能になります。
databricks pipelinesコマンドを使用してパイプライン プロジェクトを作成し、パイプラインをデプロイして実行するチュートリアルについては、 「宣言型オートメーション バンドルを使用したパイプラインの開発」をご覧ください。
変換プロセスの概要
既存のパイプラインをバンドルに変換するステップは次のとおりです。
- バンドルに変換する、以前に構成されたパイプラインにアクセスできることを確認してください。
- バンドルを保存するためのフォルダー (ソース管理された階層内が望ましい) を作成または準備します。
- Databricks CLI を使用して、既存のパイプラインからバンドルの構成を生成します。
- 生成されたバンドル構成を確認して、完了していることを確認します。
- バンドルを元のパイプラインにリンクします。
- バンドル構成を使用して、パイプラインをターゲット ワークスペースにデプロイします。
要件
始める前に、次のものが必要です。
- ローカル開発マシンにDatabricks CLIがインストールされていること。宣言型自動化バンドルを使用するには、Databricks CLI バージョン 0.218.0 以降が必要です。
- バンドルで管理する既存の宣言型パイプラインの ID。この ID を取得する方法については、 「UI を使用して既存のパイプライン定義を取得する」を参照してください。
- 既存のパイプラインが実行される Databricks ワークスペースの承認。Databricks CLI 呼び出しの認証と承認を構成するには、 「Databricks リソースへのアクセスの承認」を参照してください。
- パイプラインとその出力を作成、実行、更新、および表示するために必要な特権の全セットについては、パイプラインの ID、アクセス許可、および特権の管理を参照してください。
ステップ 1: バンドル プロジェクト用のフォルダーをセットアップする
Databricks で Git フォルダーとして構成されている Git リポジトリにアクセスできる必要があります。このリポジトリにバンドル プロジェクトを作成すると、ソース管理が適用され、対応する Databricks ワークスペースの Git フォルダーを通じて他の共同作業者が利用できるようになります。(Git フォルダーの詳細については、 「Databricks Git フォルダー」を参照してください。)
-
ローカル マシン上のクローンされた Git リポジトリのルートに移動します。
-
フォルダー階層内の適切な場所に、バンドル プロジェクト専用のフォルダーを作成します。例えば：
Bashmkdir -p ~/source/my-pipelines/ingestion/events/my-bundle -
現在の作業ディレクトリをこの新しいフォルダーに変更します。例えば：
Bashcd ~/source/my-pipelines/ingestion/events/my-bundle -
次のコマンドを実行して新しいバンドルを初期化します。
Bashdatabricks bundle init指示に従って答えてください。完了すると、プロジェクトの新しいホーム計画に
databricks.ymlという名前のプロジェクト構成ファイルが作成されます。 このファイルは、コマンドラインからパイプラインをデプロイするために必要です。この構成ファイルの詳細については、 「宣言型自動化バンドルの構成」を参照してください。
ステップ 2: パイプライン構成を生成する
複製された Git リポジトリのフォルダー ツリー内のこの新しいディレクトリから、パイプラインの ID を<pipeline-id>として指定して、Databricks CLI のバンドル生成コマンドを実行します。
databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>
generateコマンドを実行すると、バンドルのresourcesフォルダにパイプラインのバンドル構成ファイルが作成され、参照されているアーティファクトがすべてsrcフォルダにダウンロードされます。 --profile (または-pフラグ) はオプションですが、デフォルト プロファイルの代わりに使用したい特定のDatabricks構成プロファイル ( Databricks CLIをインストールしたときに作成された.databrickscfgファイルで定義) がある場合は、このコマンドでそれを指定します。 Databricks構成プロファイルの詳細については、 Databricks構成プロファイル」を参照してください。
既存のSpark宣言型パイプライン (SDP) プロジェクト ( spark-pipeline.ymlファイルがある) がある場合は、そのパイプライン プロジェクトをバンドルのsrcフォルダーにコピーし、 databricks pipelines generateコマンドを使用してそのバンドル構成を生成できます。 Databricks パイプラインの生成を参照してください。
ステップ 3: バンドル プロジェクト ファイルを確認する
bundle generateコマンドが完了すると、2 つの新しいフォルダーが作成されます。
resourcesプロジェクト構成ファイルが含まれるプロジェクト サブディレクトリです。srcクエリやノートブックなどのソース ファイルが保存されるプロジェクト フォルダーです。
このコマンドは、いくつかの追加ファイルも作成します。
*.pipeline.ymlresourcesサブディレクトリの下にあります。このファイルには、パイプラインの特定の構成と設定が含まれています。- 既存のパイプラインからコピーされた、
srcサブディレクトリ下の SQL クエリなどのソース ファイル。
├── databricks.yml # Project configuration file created with the bundle init command
├── resources/
│ └── {your-pipeline-name.pipeline}.yml # Pipeline configuration
└── src/
└── {source folders and files...} # Your pipeline's declarative queries
ステップ 4: バンドル パイプラインを既存のパイプラインにバインドします
変更を加えたときに最新の状態に保つには、バンドル内のパイプライン定義を既存のパイプラインにリンク ( バインド) する 必要があります。これを行うには、Databricks CLIバンドル デプロイメント バインド コマンドを実行します。
databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>
<pipeline-name> パイプラインの名前です。この名前は、新しいresourcesディレクトリ内のパイプライン構成のファイル名のプレフィックス付き文字列値と同じである必要があります。たとえば、 resourcesフォルダーにingestion_data_pipeline.pipeline.ymlという名前のパイプライン構成ファイルがある場合は、パイプライン名としてingestion_data_pipeline指定する必要があります。
<pipeline-ID> パイプラインの ID です。これは、この手順の要件の一部としてコピーしたものと同じです。
ステップ 5: 新しいバンドルを使用してパイプラインをデプロイします
次に、Databricks CLI のバンドル デプロイ コマンドを使用して、パイプライン バンドルをターゲット ワークスペースにデプロイします。
databricks bundle deploy --target <target-name> --profile <profile-name>
--targetフラグは必須であり、構成されたターゲット ワークスペース名 ( developmentやproductionなど) と一致する文字列に設定する必要があります。
このコマンドが成功すると、パイプライン構成が外部プロジェクトに作成され、他のワークスペースに読み込んで実行できるようになり、アカウント内の他の Databricks ユーザーと簡単に共有できるようになります。
ターゲットを使用した環境間での昇格
バンドルは、databricks.yml 内で ターゲット と呼ばれる名前付きデプロイ環境を定義し、それぞれが独自のワークスペース、カタログ、および変数値を指し示します。ターゲットは、開発、ステージング、本番運用を通じて同じパイプラインを昇格させ、編集することなく各環境に同一のソースコードをデプロイするための仕組みです。
bundle:
name: orders_pipeline
variables:
catalog:
description: Unity Catalog to write to
default: dev_catalog
targets:
dev:
mode: development
default: true
variables:
catalog: dev_catalog
prod:
mode: production
variables:
catalog: prod_catalog
run_as:
service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'
各ターゲットに設定する mode によって、デプロイメントの動作が変わります：
mode: development標的を個人的な、緊急展開としてマークする。リソースには「[dev username]7」のプレフィックスが付けられ、スケジュールはdefaultで停止されるため、あなたの仕事が他の人に影響を与えません。mode: productionそれらの安全のためのdefaultを無効にします。run_asと組み合わせることで、個人のアカウントではなくService Principalとしてパイプラインを実行できるため、チームメンバーの離職や役割変更によってランが中断されることがなくなります。Databricks では、ステージングおよび本番運用環境に対してService Principalの使用を推奨しています。service_principal_nameは、表示名ではなく、Service Principal のアプリケーション ID を受け取ります。ワークスペース管理者設定のService Principalページから、アプリケーションIDを取得できます。
モードの動作の詳細については、 「宣言型自動化バンドルのデプロイモード」および「宣言型自動化バンドルワークフローのランIDを指定する」を参照してください。
昇格させるには、 同じ バンドルを各ターゲットに順番にデプロイし、各ステージで検証を行います：
databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod
変換コード内に環境ごとのカタログ名やソースパスをハードコーディングするのではなく、ターゲットから値を渡すことで、同じソースをどこでも変更せずに実行できるようにします。それらの設定方法は、ソース言語によって異なります。パイプラインのパラメーターは、SQLソースコードにのみ適用されます。Pythonソースコードの場合は、パイプラインの configuration フィールドを使用し、spark.conf.get() で値を読み取ります：
resources:
pipelines:
orders_pipeline:
name: orders-pipeline
# For SQL source code. Reference as ${source_catalog}.
parameters:
source_catalog: ${var.catalog}
source_schema: raw
# For Python source code. Read with spark.conf.get("source_catalog").
configuration:
source_catalog: ${var.catalog}
source_schema: raw
パイプラインコードのパラメーター化の詳細については、「パイプラインでのパラメーターの使用」を参照してください。
CI/CD をセットアップする
変換されたパイプラインは完全にバンドル（YAMLとGit内のソースファイル）として定義されるため、その継続的インテグレーションと継続的デリバリー（CI/CD）をセットアップすることは、GitHub ActionsやAzure DevOpsなどのCIシステムからバンドルコマンドを実行することを意味します。各プルリクエストにおいて、適切なベースラインランは以下の通りです：
pytest単体テスト可能な変換関数に対して。パイプラインの単体テストを参照してください。databricks bundle validate --target <env>構成エラーを捕捉するため。- オプションで、サンプルデータに対する期待値を検証するためのスクラッチターゲット内の
databricks bundle run。
以下の GitHub Actions ワークフローは、保存されたトークンの代わりに OpenID Connect（OIDC）フェデレーションを使用して、main への Merge 時にステージング環境へデプロイします。
# .github/workflows/deploy.yml
name: Deploy pipeline bundle
on:
push:
branches: [main]
permissions:
id-token: write
contents: read
jobs:
deploy-staging:
runs-on: ubuntu-latest
environment: staging
env:
DATABRICKS_AUTH_TYPE: github-oidc
DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
steps:
- uses: actions/checkout@v4
- name: Install Databricks CLI
uses: databricks/setup-cli@main
- name: Validate bundle
run: databricks bundle validate --target staging
- name: Deploy bundle
run: databricks bundle deploy --target staging
本番運用展開を手動承認(例えばGitHub Environmentの承認が必要な2つ目のジョブやAzure DevOpsの別ステージ)でゲートし、各昇進を明確に承認する仕組みです。本番ジョブは、本番ワークスペースにスコープをかけたService Principalを使って databricks bundle deploy --target prod 実行されます。詳細は DatabricksのCI/CDをご覧ください。
トラブルシューティング
問題 | ソリューション |
|---|---|
実行中に「 | 現在、 |
既存のパイプライン設定が、生成されたパイプライン YAML 構成の値と一致しません | パイプライン ID はバンドル構成 YML ファイルには表示されません。その他の設定が不足していることに気付いた場合は、手動で適用できます。 |
成功のためのヒント
- 常にバージョン管理を使用してください。Databricks Git フォルダーを使用していない場合は、プロジェクトのサブディレクトリとファイルを Git またはその他のバージョン管理されたリポジトリまたはファイル システムに保存します。
- パイプラインを本番運用環境に展開する前に、非本番運用環境 (「開発」環境や「テスト」環境など) でパイプラインをテストします。 誤って誤った構成を導入してしまうことはよくあります。
その他のリソース
バンドルを使用してデータ処理を定義および管理する方法の詳細については、以下を参照してください。
- 宣言型自動化バンドルとは何ですか？
- 宣言型自動化バンドルを使用してパイプラインを開発します。このトピックでは、既存のパイプラインではなく、新しいパイプライン用のバンドルを作成する方法について説明します。このバンドルには、ユーザーが提供するバージョン管理された処理用ソースファイルが含まれます。