Databricks に関する開発者のベスト プラクティス

このページでは、バージョン管理、環境管理、開発者ツール、マネージド デプロイなど、データ エンジニアリングと開発のライフサイクルに関するベスト プラクティスを提供します。

ソース管理

すべてのファイルをバージョン管理する

宣言型オートメーションは、バージョン管理に何かが存在しない場合は存在しないという考えに基づいて構築されています。 そのため、Databricks では、次のようなほぼすべてのファイルをバージョン管理することをお勧めします。

  • すべてのノートブックとソース ファイル (.py、 .sql)
  • バンドル構成ファイル (databricks.yml および環境固有の YAML オーバーライド)

ただし、コミットしないでください。

  • .jarファイルや.whl ファイルなどの成果物をビルドします。 代わりに、CI 中にコンパイル済みのバイナリを Unity カタログ ボリュームにアップロードします。 JAR のアップロードを参照してください。
  • トークンまたは資格情報。 クラウド シークレット マネージャー (AWS Secrets Manager や Azure Key Vault など) によってサポートされるワークスペース レベルのシークレット管理を使用し、値を Databricks シークレット スコープに同期します。 「シークレットの管理」を参照してください。
  • PII を使用したローカル データの例とファイル。 .gitignoreを使用して除外します。

単一リポジトリ

Databricks では、すべてのコード (ソース コードと構成ファイル) に 1 つのリポジトリを使用することをお勧めします。これにより、コラボレーションと、人間と AI の両方に対するコードとベスト プラクティスの共有が容易になります。 個別のデプロイ ライフサイクル用に複数のバンドルがある場合は、それらを 1 つのリポジトリに保持します。

単一リポジトリの推奨事項に対する 1 つの例外は、機密保持のために複数のリポジトリが必要な規制対象の業界です。

トランクベースの分岐戦略

マージの競合を最小限に抑え、メイン ブランチが常に展開可能な状態であることを確認するには、トランクベースの分岐戦略を使用します。

単純なワークフローは次のようになります。

  1. ローカルまたはワークスペースで開発し、Databricks 開発ワークスペースにデプロイして変更をテストします。
  2. 有効期間の短い機能ブランチを作成してバージョン管理の更新を行い、ローカルまたはワークスペースの変更を定期的に同期します。
  3. テストが完了したら、機能ブランチをメイン ブランチにマージします。
  4. CI/CD によってメイン ブランチがステージング ワークスペースに自動的にデプロイされ、自動テストがトリガーされます。
  5. ステージングテストとチェックに合格すると、CI/CD はメイン ブランチを運用ワークスペースにデプロイします。

これらの手順の概要を次の図に示します。

宣言型オートメーション バンドル CI/CD 分岐戦略

ワークスペースの構成

ワークスペース環境を分離する

失敗したデプロイの影響を最小限に抑えるために、ワークスペース環境を分離します。 例えば次が挙げられます。

  • 小規模なチーム (最大 5 人のデータ エンジニア): 1 つのクラウド アカウントで 2 つのワークスペース (開発と運用) から始めます。
  • 成長するチーム (5 人を超えるデータ エンジニア): 3 つのワークスペース (開発、ステージング、運用) に移行します。 ステージングは、スケールダウンされた場合でも、運用環境 (同じバンドル構成、スキーマ、および重要な統合) を機能的に代表する必要があります。
  • 規制対象の業界 (銀行、医療、防衛): データ漏洩を防ぐために、ワークスペースとクラウド アカウントを物理的に分離します。 1 つのアカウント内で IAM と Unity カタログの境界を介して分離を管理することは可能ですが、安全性は低くなります。

運用ワークスペースの場合は、可能な場合は、ネットワーク ポリシーでサーバーレス コンピューティングを使用します。 それ以外の場合は、緊密に制御されたエグレスとネットワーク セキュリティ制御を備えたプライベート サブネットまたは VNet を使用するようにクラウド アカウントを構成します。

詳細については、「 コンテキストベースのネットワーク ポリシー」を参照してください。

データ ストレージを分離する

  • 1 つの Unity カタログ メタストアを使用し、開発、ステージング (該当する場合)、運用用に個別のカタログを作成し、ワークスペース レイアウトをミラーリングします。
  • 開発用およびステージング用の（本番環境ではない）カタログでは、各開発者に個人用スキーマを使用してください。
  • ISOLATED モードで運用カタログを運用ワークスペースにのみバインドします。 カタログの分離モードを ISOLATED に設定すると、ID が正しく構成されていない場合でも、運用環境のデータに開発環境またはステージング環境から到達できなくなります。
  • カタログ レベルの分離では満たすことができない規制、データ主権、または複数リージョンの要件を持つ組織にのみ、個別のメタストア、アカウント、またはリージョンを予約します。

テーブルと列のメタデータをコードとして扱う

テーブルと列のコメントをコードの一部として扱います。 それらを宣言型オートメーション バンドル定義と共に .sql ファイルに保持し、メタデータ ジョブを通じてデプロイして、ビジネス向けの正確な定義を常に使用できるようにします。 列名を繰り返すのではなく、行が表す内容、単位、および有効な値をプレーン言語で記述するコメントを記述します。

個人用スキーマを構成する

開発中に、 dev_${user_name}など、ユーザーごとに個人用スキーマを使用するようにバンドルを構成します。 これにより、開発者は共有ワークスペース内の互いのテーブルを上書きできなくなります。

サーバーレス コンピューティングを使用する

サーバーレス コンピューティングを使用して、クラスター管理を簡素化し、コストを最適化します。 「サーバーレス コンピューティングに接続する」を参照してください。

CI/CD の推奨事項

CI/CD 用の宣言型オートメーション バンドル

宣言型オートメーション バンドル (旧称 Databricks Asset Bundles) は、Databricks エコシステム内のコード、ワークフロー、インフラストラクチャを管理するための強力で統一されたアプローチを提供し、CI/CD パイプラインに推奨されます。

CI/CD ワークフローにバンドルを使用する方法の詳細については、 Databricks での CI/CD ワークフローに関するページを参照してください。

宣言型オートメーション バンドルの詳細については、「宣言型 オートメーション バンドルとは」を参照してください。

外部リソースにのみ Terraform を使用する

Terraform を使用して、次のリソースを定義します。

  • クラウド レベルおよび外部リソース
  • ワークスペースのプロビジョニングやクラウド ネットワークの構成など、特権のないユーザーが実行してはならない管理者アクション

他のすべての Databricks リソースに宣言型オートメーション バンドルを使用します。

バンドル管理

小さなバンドルを作成する

Databricks では、1 つの大きなバンドルに対して、小規模で焦点を絞ったバンドルを開発することをお勧めします。

  • 1 つのチームが所有するすべてのものを 1 つのバンドルに配置します。
  • 同じライフサイクルとリリース周期を共有する同じ CI/CD パイプラインを使用してテストおよびデプロイします。
  • 各バンドルは、環境ごとに個別のバンドルを使用するのではなく、特定のプロジェクト (開発、ステージング、運用) のすべての環境を対象にする必要があります。

次の目的で個別のバンドルを作成します。

  • さまざまな製品またはドメイン ("課金分析" や "不正検出" など)
  • 異なる所有権またはアクセス許可の境界
  • ライフサイクルが明確に異なるワークロード
  • 独立した昇格またはロールバックが必要な場合

sync.paths を使用して共有フォルダーを同期する

1 つのリポジトリで複数のバンドルを管理する場合は、 sync.paths を使用して、バンドル ルートの外部から共有フォルダーを同期します。 これにより、異なるプロジェクトで、個別のデプロイ ID を維持しながら、 ../commonなどの共通ライブラリ フォルダーを共有できます。

CI/CD でのバンドル間の依存関係をモデル化する

バンドル B がバンドル A によって発行されたアセットに依存している場合は、両方を 1 つのバンドルに折りたたむのではなく、CI/CD またはオーケストレーションレイヤーでその依存関係をモデル化します。

  • バンドル A のデプロイおよび発行ワークフローをバンドル B の明示的な前提条件にします。バンドル B がバンドル A のデプロイに成功し、必要なすべての検証チェックが成功した後にのみバンドル B が開始されるようにパイプラインを接続します。
  • 公開されたアセット識別子または場所をパイプラインへの入力として後続に渡し、上流のアセットが存在しない場合は即座に失敗させます。 これにより、バンドル B が部分的に公開された状態に対してデプロイされることはありません。

バンドル共有の詳細については、「 バンドルとバンドル ファイルの共有」を参照してください。

カスタム バンドル テンプレート

新しいプロジェクトの既定の開始点としてカスタム宣言型オートメーション バンドル テンプレートを使用すると、すべてのプロジェクトが同じガードレール (アクセス許可、タグ付け、クラスター ポリシー、CI/CD 配線、インスタンス ベースライン) を継承し、各チームがゼロから解決しないようにします。

テンプレートでは、ガバナンス、パフォーマンスの既定値、環境レイアウト、クォータの制限など、有効期間の長い共有規則をエンコードする必要があります。 テンプレートでは、アプリ固有のビジネス ロジック、シークレット、または 1 回限りの構成を避けます。

パラメーター化できるのは、チーム、プロジェクト、または環境によって異なると予想される入力だけです。

  • Projectまたはアプリケーション名
  • ターゲット ワークスペースの設定
  • カタログ名またはスキーマ名
  • サービス プリンシパル識別子
  • スケジュールと通知の設定

プラットフォーム ガードレールと共有の既定値は、パラメーター化するのではなく、テンプレートで固定したままにします。

カスタム バンドル テンプレートとその作成方法については、「 宣言型オートメーション バンドル プロジェクト テンプレート」を参照してください。

ロールバックとホットフィックスに備える

多数の無関係なワークロード間でロールバックを調整するのではなく、単一のバンドルでターゲットロールバックを実行できる程度の小さなバンドルを保持します。

インシデント発生時:

  1. 影響を受けるバンドルを最新の正常なバージョンに戻すかロールバックします。
  2. ホットフィックスは、通常の展開フローを待てない、緊急かつ影響範囲が限定された修正にのみ使用してください。
  3. 検証の直後に修正プログラムをメイン ブランチにマージして、トランクが信頼できる単一のソースのままになるようにします。

開発全般

サービス プリンシパルまたは OIDC を使用する

開発以外のすべての自動化にサービス プリンシパルを使用して、自動化されたワークフローを個々のユーザー アカウントから切り離し、内部ユーザーが退出してもジョブの実行を継続します。 サービス プリンシパルを参照してください。

  • デプロイとランタイムには、個別のサービス プリンシパルを使用します。 バンドルデプロイ専用のデプロイ サービス プリンシパルには、最小限のデータ アクセスが必要です。 各運用ジョブまたはパイプラインには、ワークロードに必要なデータとリソースのみを対象とする独自の実行サービス プリンシパルが必要です。 この分離により、データ アクセスのアクセス許可をローテーションまたは強化するときにデプロイを安全に保ち、運用データ アクセスに対するインフラストラクチャの変更を結合することを回避できます。
  • 規制対象の業界: CI/CD にワークロード ID フェデレーション (OIDC) を使用します。 これにより、GitHub ActionsまたはAzure DevOpsの有効期間が長いシークレットが削除されます。 CI/CD でワークロード ID フェデレーションを有効にするを参照してください。

Databricks 開発者ツールを使用する

Git フォルダーを使用して Databricks ワークスペース UI またはローカル IDE で開発します。 Visual Studio Codeまたは互換性のあるフォークを使用する場合は、公式の Databricks 拡張機能をインストールします。

  • Databricks 固有のエージェント スキル
  • Unity カタログとファイル システムへのアクセス
  • Databricks コンピューティングでワークロードを実行するためのリモート開発機能

詳細については、Visual Studio Codeの Databricks 拡張機能を参照してください。

ノートブックのビジネス ロジックを最小限に抑える

ノートブックをビジネス ロジックのプライマリ コンテナーとして扱わないでください。 探索と視覚化にのみ使用します。

  • Python: .pyまたはsrc/のインポート可能なsrc/py/ モジュールにコア ロジックを配置し、ノートブックからそれらの関数を呼び出します。
  • SQL: .sql ファイル内のクエリを src/ または src/sql/に保持し、ノートブックで SQL をインライン化するのではなく、ジョブとパイプラインからそれらのファイルを参照します。

ノートブックは、基になるコードを呼び出すシン オーケストレーションレイヤーと視覚化レイヤーとしてのみ使用します。 この方法により、テストと再利用が容易になります。

ノートブックの負荷の高いプロジェクトを移行する場合は、段階的に行います。 再利用可能なモジュールまたは SQL ファイルを一度に 1 つ抽出し、宣言型オートメーション バンドルを使用して、移行された資産をプロジェクトの残りの部分と同じデプロイおよびテスト ワークフローの下に配置します。

コンテキストを動的に渡す

タスクの依存関係には静的変数を使用しないでください。 {{tasks.<task_key>.values.<value_key>}}などの動的な値参照を使用して、マルチステージ ジョブのタスク間でランタイム コンテキストを渡します。

テストと可観測性

テスト レイヤーを実装する

バンドルが運用環境に移行する方法に一致する 3 つのテスト レイヤーを使用します。

  1. 単体テスト: インポート可能な src/ モジュールにビジネス ロジックを保持し、 pytest または同等のフレームワークでカバーします。 すべてのプルリクエストでこれらを実行し、失敗した場合はマージできないようにします。
  2. バンドルの検証: bundle validate ローカルで実行します。 CI では、運用環境のデプロイ前に YAML とリソース マッピングの問題をキャッチするために、非運用ワークスペースに bundle deploy することをお勧めします。
  3. ステージングでの統合テスト: ステージングにデプロイした後、完了チェックと、行数やスキーマの期待などの重要なデータ品質アサーションを使用してエンド ツー エンド のジョブを実行します。

アーティファクトを本番環境に昇格させるゲートとして、"メイン ブランチとステージング環境ですべてのテストに合格している" を扱います。

Lakeflow Spark 宣言型パイプラインの場合は、アドホック ノートブックの実行ではなく、組み込みの開発および検証機能を使用します。 エラーのあるレコードを含む小規模で代表的なデータセットに対してパイプライン ロジックをテストし、開発モードを使用して、運用テーブルを更新する前に変更を検証します。

デプロイの一部としてログ記録を処理する

宣言型オートメーション バンドルでデプロイされたワークロードの場合は、各プロジェクトが個別に定義するのではなく、メトリックとログをデプロイ コントラクトの一部として扱います。

  • ジョブ、パイプライン、タスク間で一貫して構造化されたログを出力します。 バンドル名、ターゲット環境、ワークロード名、実行識別子、および障害をトレースするために必要なビジネス識別子を含めます。
  • すべての運用ワークロードの標準の一連の運用メトリックを追跡します。実行状態、期間、再試行回数、スループットまたは鮮度インジケーター (該当する場合)。
  • 共有ライブラリ、再利用可能なワークロード定義、またはバンドル テンプレートでこれらの規則をエンコードして、チームが各プロジェクトの可観測パターンを再作成する必要がないようにします。
  • Last updated on