初期化アクション

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

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

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

  • 公開バケットの gs://goog-dataproc-initialization-actions-REGION 内にある初期化アクションを参照して使用する本番環境クラスタは、作成しないでください。一般公開バケットのスクリプトはリファレンス実装として提供されているもので、進行中の GitHub リポジトリの変更と同期されており、その初期化アクションが更新されると、クラスタの作成が中断する可能性があります。参照して使用するのではなく、次の例に示すように、初期化アクションを一般公開バケットから自分のバケットにコピーして使用します。

    REGION=region
    
    gsutil cp gs://goog-dataproc-initialization-actions-${REGION}/tez/tez.sh gs://my-bucket
    
    次に、コピーを参照してクラスタを作成します。
    gcloud dataproc clusters create cluster-name \
        --region=${REGION} \
        --initialization-actions=gs://my-bucket/tez.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 カスタム イメージを使用して、ジョブの依存関係を設定することもできます。

  • 初期化処理:

    • 2.0 より前のイメージのクラスタ:
      • マスター: HDFS の書き込みが可能になるまで(HDFS がセーフモードを終了して、少なくとも 2 つの HDFS DataNode が結合されるまで)、マスターノードの初期化アクションは動作しません。これにより、初期化アクションがマスター上で動作し、HDFS にファイルが書き込めるようになります。
      • ワーカー: ユーザーが dataproc:dataproc.worker.custom.init.actions.mode クラスタ プロパティRUN_BEFORE_SERVICES に設定した場合、各ワーカーは、HDFS データノードと YARN nodemanager デーモンを開始する前に初期化アクションを実行します。Dataproc は HDFS が書き込み可能になるまでマスター初期化アクションを実行せず、これにより HDFS datanode デーモンが 2 つ動く必要が生じるため、このプロパティを設定すると、クラスタ作成時間が長くなる可能性があります。
    • 2.0 以上のイメージのクラスタ:

      • マスター: HDFS が書き込み可能になる前に、マスターノードの初期化アクションを実行できます。HDFS にファイルをステージングする初期化アクションを実行すると、HDFS が書き込み可能になるまで、再試行するかポーリングする必要があります。
      • ワーカー: クラスタが作成されたとき、dataproc:dataproc.worker.custom.init.actions.mode クラスタ プロパティRUN_BEFORE_SERVICES に設定されており、クラスタに渡すことはできません(ユーザーはそれを変更できません)。各ワーカーは、初期化アクションを実行した後、HDFS datanode と YARN nodemanager デーモンを開始します。Dataproc は、マスター初期化アクションの実行を HDFS が書き込み可能になるまで待つことはしないため、マスター初期化アクションとワーカー初期化アクションは並列に実行されます。
    • 推奨:

      • メタデータを使用してノードで初期化アクションを条件付きで実行できるノードのロールを決定します(クラスタ メタデータの使用をご覧ください)。
      • 初期化アクションのコピーを 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 つ以上のスクリプトまたは実行可能ファイルを指定します。

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

  • Dataproc の [クラスタの作成] ページを開き、[クラスタのカスタマイズ] パネルを選択します。
  • [初期化アクション] セクションで、[実行可能ファイル] フィールドに各初期化アクションの Cloud Storage バケットのロケーションを入力します。[BROWSE] をクリックして、Cloud Console の 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
      ... 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 に記録されます。

    次のステップ

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