Databricks Init Scripts: クラスタ初期化・依存関係配布

Databricksクラスタの起動時にカスタムの初期化処理を実行したい場面は多くあります。 OSライブラリのインストール、セキュリティエージェントの配置、環境変数の設定、 モニタリングツールの起動など、Init Scriptsはクラスタ環境のカスタマイズに不可欠な仕組みです。 この記事では、Init Scriptsの種類、配置場所、実行順序、制約事項、トラブルシューティングまでを整理します。

Init Scriptsの種類

Init Scriptsは適用範囲と設定方法によって以下の3種類に分けられます。

Cluster-scoped Init Scriptは特定のクラスタだけにカスタム環境を適用したいときに使い、 Global Init Scriptはセキュリティエージェントのように全クラスタで統一的に実行したい処理に使います。

配置場所の選択肢

Unity Catalog環境では、Volumesへの配置がベストプラクティスです。 Volumesに配置すると、スクリプトへのアクセスがUnity Catalogの権限モデルで管理され、 誰がいつスクリプトを変更したかの監査ログも取得できます。

実行順序

クラスタ起動時に複数のInit Scriptが存在する場合、以下の順序で実行されます。

1. Global Init Scripts（Admin Settingsで登録された順序）
2. Cluster-scoped Init Scripts（クラスタ設定で指定された順序）

Global Init Scriptsが先に実行されるため、全クラスタ共通の基盤設定（セキュリティ、モニタリング）を Globalで行い、クラスタ固有のカスタマイズ（特定ライブラリのインストール等）をCluster-scopedで行う 設計が一般的です。

各スクリプト内では上から順にシェルコマンドが実行され、途中でexit 1等の非ゼロ終了コードが 返されるとクラスタの起動が失敗します。

Init Scriptの記述例

#!/bin/bash
# 環境変数の設定
echo "export ENVIRONMENT=production" >> /etc/environment

# OS依存パッケージのインストール
apt-get update -y && apt-get install -y libgeos-dev

# Python追加ライブラリのインストール
/databricks/python/bin/pip install geopy==2.4.1

# モニタリングエージェントの起動
if [ -f /opt/monitoring/agent.sh ]; then
  /opt/monitoring/agent.sh start
fi

スクリプトは冪等（何回実行しても同じ結果）になるように書くことが重要です。 クラスタの再起動やリサイズのたびにInit Scriptが再実行されるため、 既にインストール済みのパッケージを再インストールしても問題ないようにします。

Shared Mode / Unity Catalog Shared Clusterの制約

Shared Access Modeのクラスタ（複数ユーザーが共有するクラスタ）では、Init Scriptに重要な制約があります。

• Cluster-scoped Init Scriptは利用不可（セキュリティ上の理由）
• Global Init Scriptのみ実行可能
• スクリプト内でのファイルシステム操作が一部制限される
• ユーザーがクラスタ設定を変更できないため、管理者がGlobal Init Scriptで必要な環境を整える必要がある

Single User Access Modeのクラスタでは、Cluster-scoped Init Scriptが利用可能です。 この違いは試験で問われやすいポイントです。

ログ確認方法

Init Scriptの実行結果はクラスタのドライバーノード上のログに保存されます。

Serverless Computeとの関係

Serverless Compute（SQL Warehouse Serverless / Serverless Notebooks）ではInit Scriptは実行できません。 Serverless環境はDatabricksが完全にマネージドするため、ユーザーによるOSレベルのカスタマイズは許可されません。

Serverless環境でライブラリを追加するには以下の方法を使います。

• ノートブック内で%pip installを使う
• Workspace Librariesで管理されたライブラリを使用する
• Unity Catalog Volumesにホイールファイルを配置し、%pip install /Volumes/...で参照する

トラブルシューティング

クラスタが起動しない

• Event Logで「INIT_SCRIPT_FAILURE」を確認する
• ドライバーログで標準エラー出力を確認し、原因（apt-getの失敗、権限不足、ネットワークエラー等）を特定する
• スクリプトの先頭にset -exを追加してデバッグ出力を有効にする

スクリプトが途中で止まる

• apt-get等の対話型プロンプトが表示され待機状態になっている可能性 → -yフラグの付与を確認
• ネットワークタイムアウト → --timeoutや--retryオプションを追加

再起動のたびに時間がかかる

• 大きなパッケージのダウンロード → パッケージをVolumesに事前配置し、ローカルインストールに切り替える
• 不要な処理の実行 → 条件分岐（if [ ! -f /opt/already_installed ]; then ...）で冪等性を確保

試験で問われるポイント

• 「Shared Access Modeのクラスタでカスタムライブラリを全ノードにインストールするには」→ Global Init Script
• 「Init ScriptをUnity Catalog管理下に置くには」→ Volumesに配置
• 「Init Scriptの失敗はクラスタにどう影響するか」→ クラスタの起動が失敗する
• 「Serverless ComputeでOSパッケージを追加するには」→ 不可。%pip installでPythonパッケージのみ対応

問題で確認

よくある質問