初期化アクション

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

よく使用される初期化アクション スクリプトとその他のサンプルの初期化アクション スクリプトについては、次の場所で参照できます。

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

  • gs://goog-dataproc-initialization-actions-<REGION>> 公開バケット内にある初期化アクションを参照する本番環境クラスタを作成しないでください。このスクリプトはリファレンス実装として提供されているもので、進行中の GitHub リポジトリの変更と同期されています。新しいバージョンでは、一般公開バケットにある初期化アクションでクラスタの作成が中断する可能性があります。代わりに、次の例に示すように、初期化アクションを一般公開バケットからご自身のバケットにコピーします。
    REGION=region
    
    gsutil cp gs://goog-dataproc-initialization-actions-${REGION}/presto/presto.sh gs://my-bucket/
    
    次に、コピーを参照してクラスタを作成します。
    gcloud dataproc clusters create cluster-name \
        --region=${REGION} \
        --initialization-actions=gs://my-bucket/presto.sh \
        ... other flags ...
    
    一般公開バケットまたは GitHub リポジトリで発生する初期化アクションの変更と初期化アクションのコピーを同期するタイミングを決定できます。
  • 初期化アクションは、クラスタの作成時に各ノードで実行されます。また、クラスタがスケーリングまたは自動スケーリングされるときも、新しく追加される各ノードで実行されます。
  • 初期化アクションは root ユーザーとして実行します。つまり、sudo を使用する必要がありません。
  • 初期化アクションでは絶対パスを使用する必要があります。
  • 初期化アクションでは、シバン行を使用してスクリプトの解釈方法を指定する必要があります(#!/bin/bash#!/usr/bin/python)。
  • 初期化アクションがゼロ以外の終了コードで終了すると、クラスタ作成オペレーションは「ERROR」ステータスを報告します。初期化アクションをデバッグするには、クラスタの VM インスタンスに SSH 接続し、ログを確認します。初期化アクションの問題を修正したら、クラスタを削除のうえ再作成できます。
  • 内部 IP アドレスのみの Dataproc クラスタを作成する場合、Cloud NATまたは Cloud VPN 経由でトラフィックを送信するようにルートを構成していない限り、初期化アクションで github.com にインターネット経由でアクセスしようとしても失敗します。インターネットにアクセスできない場合、限定公開の Google アクセスを有効にして、Cloud Storage 内にジョブの依存関係を配置します。これにより、クラスタノードは内部 IP を使用して、Cloud Storage 内に配置された依存関係をダウンロードできます。
  • 初期化アクションの代わりに Dataproc カスタム イメージを使用して、ジョブの依存関係を設定することもできます。
  • 初期化処理:
    • HDFS が書き込み可能になるまで(HDFS のセーフモードが終了し、2 つ以上の HDFS DataNode が結合されるまで)、マスターノードの初期化アクションは開始されません。これにより、マスターで実行される初期化アクションによって HDFS にファイルを書き込むことができます。
    • dataproc:dataproc.worker.custom.init.actions.mode=RUN_BEFORE_SERVICES クラスタ プロパティが設定されている場合、各ワーカーは HDFS DataNode デーモンを起動する前に初期化アクションを実行します。マスターの初期化アクションは、少なくとも 2 つのワーカーが初期化アクションを完了するまで開始されません。これによって、クラスタ作成時間が長くなる可能性があります。
    • 各クラスタノードでは、複数の初期化アクションがクラスタ作成コマンドで指定された順に実行されます。ただし、個別のノードの初期化アクションは独立して処理されます。ワーカーの初期化アクションは、マスターの初期化アクションと同時に、その前、または後に実行されます。
    • クラスタを作成するときにユーザーが選択したオプション コンポーネントが、初期化アクションがクラスタで実行される前にクラスタにインストールされ、有効にされます。
    • 推奨事項:
      • メタデータを使用してノードで初期化アクションを条件付きで実行できるノードのロールを決定します(クラスタ メタデータの使用を参照)。
      • 初期化アクションのコピーを Cloud Storage バケットにフォークして安定性を確保します(初期化アクションの使用方法を参照)。
      • インターネットからダウンロードするときに再試行を追加して行い、初期化アクションを安定させます。

初期化アクションの使用

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

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 クラスタプロパティを使用します。

REST API

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

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"
      }
    ]
  }
}

Console

Cloud Console でクラスタを作成するときは、Initialization actions 項目で 1 つ以上の初期化アクションを指定できます。この項目を表示するには、[詳細オプション] パネルを展開します。
このフォームでそれぞれの初期化アクションの Cloud Storage の場所を入力します。[参照] をクリックして Cloud Console の [Cloud Storage ブラウザ] ページを開き、初期化ファイルを選択します。各初期化ファイルは別々に入力する必要があります(新しいエントリを追加するには、Enter キーを押します)。

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

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
  ... 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
  gsutil 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 に記録されます。

次のステップ

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