初期化アクション

Dataproc クラスタを作成するときは、クラスタを設定した直後に Dataproc が Dataproc クラスタ内のすべてのノードで実行する初期化アクションとして実行可能ファイルまたはスクリプトを指定できます。初期化アクションは、ジョブの実行時に依存関係をインストールしなくてもジョブをクラスタに送信できるよう、Python パッケージのインストールなど、ジョブの依存関係を設定するために多く用いられます。

初期化アクションスクリプトのサンプルは、次の場所にあります。注: Google ではこれらのサンプルをサポートしていません。

GitHub リポジトリ
Cloud Storage - リージョン gs://goog-dataproc-initialization-actions-REGION 公開バケット内

重要な考慮事項とガイドライン

公開バケットの gs://goog-dataproc-initialization-actions-REGION 内にある初期化アクションを参照して使用する本番環境クラスタは、作成しないでください。これらのスクリプトは、リファレンス実装として提供されています。これらは進行中の GitHub リポジトリの変更と同期されており、これらのスクリプトを更新すると、クラスタの作成が中断する可能性があります。代わりに、次の例に示すように、初期化アクションを一般公開バケットからバージョニングされた Cloud Storage バケットフォルダにコピーします。
```
REGION=COMPUTE_REGION
gcloud storage cp gs://goog-dataproc-initialization-actions-${REGION}/cloud-sql-proxy/cloud-sql-proxy.sh \
    gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh
```
次に、Cloud Storage 内のコピーを参照してクラスタを作成します。
```
gcloud dataproc clusters create CLUSTER_NAME \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh \
    ...other flags...
```
初期化アクションは、クラスタの作成時に各ノードで順番に実行されます。また、クラスタがスケーリングまたは自動スケーリングによって拡大するときも、追加される各ノードで実行されます。
初期化アクションを更新するとき（たとえば、Cloud Storage の初期化アクションを一般公開のバケットや GitHub リポジトリの初期化アクションに加えられた変更と同期する場合）は、新しい（できればバージョン名の）フォルダを作成して、更新された初期化アクションを受信します。そうではなく、初期化アクションをインプレースで更新した場合、新しいノード（たとえば、オートスケーラーによって追加されたノードなど）において、インプレースで更新した初期化アクションが実行されます。このとき、既存のノードで実行されていた以前のバージョンの初期化アクションは実行されません。このような初期化アクションの違いにより、クラスタノードに不整合や破損が発生する可能性があります。
初期化アクションは root ユーザーとして実行します。sudo を使用する必要はありません。
初期化アクションで絶対パスを使用します。
初期化アクションでシバン行を使用して、スクリプトの解釈方法を指定します（#!/bin/bash や #!/usr/bin/python など）。
初期化アクションがゼロ以外の終了コードで終了すると、クラスタ作成オペレーションは「ERROR」ステータスを報告します。初期化アクションをデバッグするには、SSH を使用してクラスタの VM インスタンスに接続してから、ログを確認します。初期化アクションの問題を修正したら、クラスタを削除のうえ再作成できます。
内部 IP アドレスのみで Dataproc クラスタを作成する場合、Cloud NAT または Cloud VPN 経由でトラフィックを送信するようにルートを構成していない限り、初期化アクションで github.com にインターネット経由でアクセスしようとしても失敗します。インターネットにアクセスせずに、限定公開の Google アクセスを有効にして、Cloud Storage 内にジョブの依存関係を配置できます。これにより、クラスタノードは内部 IP を使用して、Cloud Storage から依存関係をダウンロードできます。
初期化アクションの代わりに Dataproc カスタムイメージを使用して、ジョブの依存関係を設定することもできます。
初期化処理:
- 2.0 より前のイメージのクラスタ:
  - マスター: HDFS にファイルを書き込むために、初期化アクションがマスター上で実行されるようにするために、HDFS が書き込み可能になるまで（HDFS がセーフモードを終了し、少なくとも 2 つの HDFS データノードが結合されるまで）、マスターノードの初期化アクションは開始されません。
  - ワーカー: dataproc:dataproc.worker.custom.init.actions.modeクラスタプロパティを RUN_BEFORE_SERVICES に設定すると、各ワーカーは HDFS データノードと YARN ノードマネージャーデーモンを起動する前に、初期化アクションを実行します。Dataproc は HDFS が書き込み可能になるまでマスター初期化アクションを実行せず、これにより HDFS datanode デーモンが 2 つ動く必要が生じるため、このプロパティを設定すると、クラスタ作成時間が長くなる可能性があります。
- 2.0 以上のイメージのクラスタ:
  - マスター: HDFS が書き込み可能になる前に、マスターノードの初期化アクションを実行できます。HDFS でファイルをステージングする初期化アクションを実行するか、Ranger などの HDFS 依存サービスの可用性に依存する場合は、dataproc.master.custom.init.actions.mode クラスタプロパティを RUN_AFTER_SERVICES に設定します。注: このプロパティを設定するとクラスタ作成時間が長くなる可能性があるため（2.0 以前のイメージクラスタワーカーのクラスタ作成遅延に関する説明をご覧ください）、必要な場合にのみ使用します（一般的な実施では、このプロパティのデフォルトの RUN_BEFORE_SERVICES 設定に頼ります）。
  - ワーカー: dataproc:dataproc.worker.custom.init.actions.mode クラスタプロパティは、クラスタの作成時に RUN_BEFORE_SERVICES に設定され、クラスタに渡せません。（プロパティ設定は変更できません）。各ワーカーは、初期化アクションを実行した後、HDFS datanode と YARN nodemanager デーモンを開始します。Dataproc は、マスター初期化アクションの実行を HDFS が書き込み可能になるまで待つことはしないため、マスター初期化アクションとワーカー初期化アクションは並列に実行されます。
- 推奨:
  - メタデータを使用してノードで初期化アクションを条件付きで実行できるノードのロールを決定します（クラスタメタデータの使用をご覧ください）。
  - 初期化アクションのコピーを Cloud Storage バケットにフォークして安定性を確保します（初期化アクションの使用方法をご覧ください）。
  - インターネットからのダウンロードに再試行を加えて、初期化アクションを安定させます。

初期化アクションの使用

クラスタ初期化アクションは、クラスタの作成方法に関係なく指定できます。

Google Cloud Console の使用
gcloud CLI の使用
Dataproc clusters.create API によるプログラムを使用する（NodeInitializationAction を参照）

gcloud コマンド

gcloud dataproc clusters create コマンドでクラスタを作成するときは、--initialization-actions フラグを使用して、初期化の実行可能ファイルまたはスクリプトの 1 つ以上のカンマ区切りの Cloud Storage の場所（URI）を指定します。注: Cloud Storage の場所 URI の最初の「gs://」の後への複数の連続した「/」（「gs://bucket/my//object//name」など）の使用はサポートされていません。コマンド情報を確認するには、gcloud dataproc clusters create --help を実行します。

gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --initialization-actions=Cloud Storage URI(s) (gs://bucket/...) \
    --initialization-action-timeout=timeout-value (default=10m) \
    ... other flags ...

注:

初期化アクションのタイムアウト期間を指定するには、--initialization-action-timeout フラグを使用します。デフォルトのタイムアウト値は 10 分です。タイムアウト期間が終了するまでに初期化実行可能ファイルやスクリプトが完了しないと、Dataproc により初期化アクションがキャンセルされます。
ノードマネージャと datanode デーモンを起動する前にプライマリワーカーで初期化アクションを実行するには、dataproc:dataproc.worker.custom.init.actions.mode クラスタプロパティを使用します。

Cloud Console にクラスタ作成リクエストを作成させるDataproc の [クラスタの作成] ページの左パネルの下部にある [同等の REST またはコマンドライン] リンクをクリックして、Google Cloud コンソールにより同等の API REST リクエストまたは gcloud ツールコマンドを作成します（注: Google Cloud コンソールには REST API の executionTimeout フィールドや、Google Cloud CLI の --initialization-action-timeout フラグは含まれません）。

REST API

clusters.create API リクエストの中で ClusterConfig.initializationActions 配列に 1 つ以上のスクリプトまたは実行可能ファイルを指定します。

例

POST /v1/projects/my-project-id/regions/us-central1/clusters/
{
  "projectId": "my-project-id",
  "clusterName": "example-cluster",
  "config": {
    "configBucket": "",
    "gceClusterConfig": {
      "subnetworkUri": "default",
      "zoneUri": "us-central1-b"
    },
    "masterConfig": {
      "numInstances": 1,
      "machineTypeUri": "n1-standard-4",
      "diskConfig": {
        "bootDiskSizeGb": 500,
        "numLocalSsds": 0
      }
    },
    "workerConfig": {
      "numInstances": 2,
      "machineTypeUri": "n1-standard-4",
      "diskConfig": {
        "bootDiskSizeGb": 500,
        "numLocalSsds": 0
      }
    },
    "initializationActions": [
      {
        "executableFile": "gs://cloud-example-bucket/my-init-action.sh"
      }
    ]
  }
}

Google Cloud コンソールにクラスタ作成リクエストを作成させます。: Dataproc の [クラスタの作成] ページの左パネルの下部にある [同等の REST API またはコマンドライン] リンクをクリックして、Google Cloud コンソールが同等の API REST リクエストまたは gcloud ツールコマンドを作成するようにします（注: Google Cloud コンソールには REST の executionTimeout フィールドや、Google Cloud CLI の --initialization-action-timeout フラグは含まれません）。

Console

Dataproc の [クラスタの作成] ページを開き、クラスタのカスタマイズ パネルを選択します。

[初期化アクション] セクションで、[実行可能ファイル] フィールドに各初期化アクションの Cloud Storage バケットの場所を入力します。[ブラウジング] をクリックして、Google Cloud コンソールの Cloud Storage ブラウザページを開き、スクリプトまたは実行可能ファイルを選択します。初期化のアクションを追加 をクリックして、新しいファイルを追加します。

初期化アクションに引数を渡す

Dataproc は、クラスタ内で実行されるインスタンスに対して特別なメタデータを設定します。初期化アクションに引数を渡す方法として、独自のカスタムメタデータを設定できます。

gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --initialization-actions=Cloud Storage URI(s) (gs://bucket/...) \
    --metadata=name1=value1,name2=value2... \
    ... other flags ...

メタデータ値は、初期化アクション内で次のように読み取ることができます。

var1=$(/usr/share/google/get_metadata_value attributes/name1)

ノード選択

初期化アクションをマスターノード、ドライバまたはワーカーノードに限定する場合は、単純なノード選択ロジックを実行可能ファイルまたはスクリプトに追加します。

ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
if [[ "${ROLE}" == 'Master' ]]; then
  ... master specific actions ...
else if [[ "${ROLE}" == 'Driver' ]]; then
  ... driver specific actions ...
else
  ... worker specific actions ...
fi

バイナリのステージング

よくあるクラスタ初期化シナリオは、ジョブを送信するたびにジョブバイナリをステージングしなくてもよいようにクラスタでジョブバイナリをステージングすることです。たとえば、次の初期化スクリプトが gs://my-bucket/download-job-jar.sh（Cloud Storage バケットの場所）に保存されているとします。

#!/bin/bash
ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
if [[ "${ROLE}" == 'Master' ]]; then
  gcloud storage cp gs://my-bucket/jobs/sessionalize-logs-1.0.jar home/username
fi

このスクリプトの場所を gcloud dataproc clusters create コマンドに渡すことができます。

gcloud dataproc clusters create my-dataproc-cluster \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/download-job-jar.sh

Dataproc は、すべてのノードに対してこのスクリプトを実行し、スクリプトのノード選択ロジックに従って jar をマスターノードにダウンロードします。送信したジョブでこの事前にステージングした jar を使用できます。

gcloud dataproc jobs submit hadoop \
    --cluster=my-dataproc-cluster \
    --region=${REGION} \
    --jar=file:///home/username/sessionalize-logs-1.0.jar

初期化アクションのサンプル

よく使用される初期化アクションスクリプトとその他のサンプル初期化アクションスクリプトを公開 Cloud Storage バケット（gs://goog-dataproc-initialization-actions-<REGION>）と GitHub リポジトリで公開しています。スクリプトを投稿するには、CONTRIBUTING.md のドキュメントを確認し、pull リクエストをお送りください。

ロギング

各初期化アクションの実行による出力は、インスタンスごとに /var/log/dataproc-initialization-script-X.log に記録されます。X は、各初期化アクションスクリプトに対しゼロから順につけられるインデックスです。たとえば、クラスタに 2 つの初期化アクションがある場合、出力は /var/log/dataproc-initialization-script-0.log と /var/log/dataproc-initialization-script-1.log に記録されます。

次のステップ

GitHub の初期化アクションを確認します。