ワークフロー テンプレートのパラメータ化

ワークフロー テンプレートに別の値を指定して何度も使用できれば、その都度テンプレートのパラメータ定義を行ってワークフローを編集する必要がなくなります。これをテンプレートのパラメータ化と言います。これを行うことにより、テンプレートを使用するたびにパラメータに別の値を渡すことができます。

パラメータ化可能なフィールド

パラメータ化可能な Cloud Dataproc ワークフロー テンプレート フィールドは、次のとおりです。

  • ラベル
  • ファイルの URI
  • マネージド クラスタ名。Dataproc は、ユーザー指定の名前を名前の前部に使用し、その後ろにランダムな文字を追加して重複しないクラスタ名を作成します。クラスタはワークフローの最後に削除されます。
  • ジョブのプロパティ
  • ジョブの引数
  • スクリプトの変数(HiveJob、SparkSqlJob、PigJob)
  • メインクラス(HadoopJob、SparkJob)
  • ゾーン(ClusterSelector)
  • マスター インスタンス グループまたはワーカー インスタンス グループのインスタンス数(numInstances)。

パラメータ属性

ワークフロー テンプレート パラメータは、次に挙げる必須の属性とオプションの属性で定義されます。

name(必須)
unix スタイルの変数名。後でパラメータの値を指定するときに、この名前がキーとして使用されます。
fields(必須)
パラメータで置き換えられるフィールドのリスト(パラメータ化できるフィールドのリストは、パラメータ化可能なフィールドをご覧ください)。各フィールドは「フィールドパス」として指定されます(フィールドパスの指定に使用する構文は、フィールドパスの構文をご覧ください)。各フィールドは、1 つのパラメータのフィールドパス リストにのみ指定できます。
description(省略可)
パラメータの簡単な説明。
validation(省略可)
パラメータ値の検証に使用するルール。次のいずれかを使用できます。
  1. 使用できる値のリスト
  2. 値が一致する必要のある正規表現のリスト。

フィールドパスの構文

フィールドパスは FieldMask の構文に似ています。たとえば、ワークフロー テンプレートのクラスタ セレクタの zone フィールドを参照するフィールドパスは、placement.clusterSelector.zone と指定します。

フィールドパスでは、次の構文を使用してフィールドを参照できます。

  • マネージド クラスタ名:

    • placement.managedCluster.clusterName
  • マップの値は、次の例のようにキーを指定して参照できます。

    • labels['キー']
    • placement.clusterSelector.clusterLabels['キー']
    • placement.managedCluster.labels['キー']
    • jobs['step-id'].labels['キー']
  • ジョブリストのジョブは、次のようにステップ ID を指定して参照できます。

    • jobs['ステップ ID'].hadoopJob.mainJarFileUri
    • jobs['ステップ ID'].hiveJob.queryFileUri
    • jobs['ステップ ID'].pySparkJob.mainPythonFileUri
    • jobs['ステップ ID'].hadoopJob.jarFileUris[0]
    • jobs['ステップ ID'].hadoopJob.archiveUris[0]
    • jobs['ステップ ID'].hadoopJob.fileUris[0]
    • jobs['ステップ ID'].pySparkJob.pythonFileUris[0]

    • 繰り返しフィールドのアイテムは、次の例のようにゼロ始まりのインデックスを指定して参照できます。

    • jobs['ステップ ID'].sparkJob.args[0]

    • その他の例:

    • jobs['ステップ ID'].hadoopJob.args[0]

    • jobs['ステップ ID'].hadoopJob.mainJarFileUri

    • jobs['ステップ ID'].hadoopJob.properties['キー']

    • jobs['ステップ ID'].hiveJob.scriptVariables['キー']

    • placement.clusterSelector.zone

マップ全体や繰り返しフィールド全体をパラメータ化することはできません。現時点で参照できるのは、個々のマップ値と、繰り返しフィールド内の個々のアイテムのみです。たとえば、以下のフィールドパスは無効です。

placement.clusterSelector.clusterLabels
jobs['step-id'].sparkJob.args

ワークフロー テンプレートのパラメータ化

ワークフロー テンプレートをパラメータ化するには、Dataproc API または gcloud コマンドライン ツールを使用してテンプレート パラメータを定義します。

gcloud コマンド

gcloud コマンドライン ツールを使用して、ワークフロー テンプレート パラメータを作成またはエクスポートして定義します。次に、ワークフロー テンプレート YAML ファイルを編集してから、gcloud コマンドライン ツールでこのファイルをインポートし、テンプレートを作成または更新します。詳細については、YAML ファイルの使用をご覧ください。

例 1: パラメータ化されたマネージドクラスタ テンプレートの例

4 つのパラメータ(CLUSTER、NUM_ROWS、GEN_OUT、SORT_OUT)が定義された teragen-terasort マネージドクラスタワークフロー テンプレート YAML ファイルの例を次に示します。パラメータ化前およびパラメータ化後の 2 つのバージョンを記載します。

    placement:
      managedCluster:
        clusterName: my-managed-cluster
        config:
          gceClusterConfig:
            zoneUri: us-central1-a
    jobs:
    - hadoopJob:
        args:
        - teragen
        - '10000'
        - hdfs:///gen/
        mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
      stepId: teragen
    - hadoopJob:
        args:
        - terasort
        - hdfs:///gen/
        - hdfs:///sort/
        mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
      prerequisiteStepIds:
      - teragen
      stepId: terasort
    

    placement:
      managedCluster:
        clusterName: 'to-be-determined'
        config:
          gceClusterConfig:
            zoneUri: us-central1-a
    jobs:
    - hadoopJob:
        args:
        - teragen
        - '10000'
        - hdfs:///gen/
        mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
      stepId: teragen
    - hadoopJob:
        args:
        - terasort
        - hdfs:///gen/
        - hdfs:///sort/
        mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
      prerequisiteStepIds:
      - teragen
      stepId: terasort
    parameters:
    - description: The managed cluster name prefix
      fields:
      - placement.managedCluster.clusterName
      name: CLUSTER
    - description: The number of rows to generate
      fields:
      - jobs['teragen'].hadoopJob.args[1]
      name: NUM_ROWS
      validation:
        values:
          values:
          - '1000'
          - '10000'
          - '100000'
    - description: Output directory for teragen
      fields:
      - jobs['teragen'].hadoopJob.args[2]
      - jobs['terasort'].hadoopJob.args[1]
      name: GEN_OUT
      validation:
        regex:
          regexes:
          - hdfs:///.*
    - description: Output directory for terasort
      fields:
      - jobs['terasort'].hadoopJob.args[2]
      name: SORT_OUT
      validation:
        regex:
          regexes:
          - hdfs:///.*
    

例 2: クラスタ セレクタ ワークフロー テンプレートの例

3 つのパラメータ(CLUSTER、NUM_ROWS、OUTPUT_DIR)が定義されたパラメータ化された teragen-terasort クラスタ セレクタ ワークフローテンプレート YAML ファイルの例を次に示します。

    placement:
      clusterSelector:
        clusterLabels:
          goog-dataproc-cluster-name: 'to-be-determined'
    jobs:
      - stepId: teragen
        hadoopJob:
          args:
          - 'teragen'
          - 'tbd number of rows'
          - 'tbd output directory'
    parameters:
    - name: CLUSTER
      fields:
      - placement.clusterSelector.clusterLabels['goog-dataproc-cluster-name']
    - name: NUM_ROWS
      fields:
      - jobs['teragen'].hadoopJob.args[1]
    - name: OUTPUT_DIR
      fields:
      - jobs['teragen'].hadoopJob.args[2]
    

テンプレート パラメータでワークフロー テンプレートを定義する YAML ファイルを作成または編集した後、次の gcloud コマンドを使用して YAML ファイルをインポートして、パラメータ化テンプレートを作成または更新します。

    gcloud dataproc workflow-templates import template-ID or template-name \
      --source template.yaml
    

WorkflowTemplateid と完全修飾テンプレート リソース name("projects/projectId/regions/region/workflowTemplates/template_id")のどちらでもコマンドに渡すことが可能です。同じ名前のテンプレート リソースが存在する場合は、上書き(更新)されてバージョン番号が大きくなります。同じ名前のテンプレートが存在しない場合は、作成されます。

Rest API

1 つ以上の WorkflowTemplate.parametersworkflowTemplates.create または workflowTemplates.update の API リクエストで定義できます。

4 つの定義済みパラメータ(CLUSTER、NUM_ROWS、GEN_OUT、SORT_OUT)を使用して teragen-terasort ワークフロー テンプレートを作成する、workflowTemplates.create リクエストの例を次に示します。

    POST https://dataproc.googleapis.com/v1/projects/my-project/locations/us-central1/workflowTemplates
    {
      "id": "my-template",
      "jobs": [
        {
          "stepId": "teragen",
          "hadoopJob": {
            "mainJarFileUri": "file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar",
            "args": [
              "teragen",
              "10000",
              "hdfs:///gen/"
            ]
          }
        },
        {
          "stepId": "terasort",
          "prerequisiteStepIds": [
            "teragen"
          ],
          "hadoopJob": {
            "mainJarFileUri": "file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar",
            "args": [
              "terasort",
              "hdfs:///gen/",
              "hdfs:///sort/"
            ]
          }
        }
      ],
      "parameters": [
        {
          "name": "CLUSTER",
          "fields": [
            "placement.managedCluster.clusterName"
          ],
          "description": "The managed cluster name prefix"
        },
        {
          "name": "NUM_ROWS",
          "fields": [
            "jobs['teragen'].hadoopJob.args[1]"
          ],
          "description": "The number of rows to generate",
          "validation": {
            "values": {
              "values": [
                "1000",
                "10000",
                "100000"
              ]
            }
          }
        },
        {
          "name": "GEN_OUT",
          "fields": [
            "jobs['teragen'].hadoopJob.args[2]",
            "jobs['terasort'].hadoopJob.args[1]"
          ],
          "description": "Output directory for teragen",
          "validation": {
            "regex": {
              "regexes": [
                "hdfs:///.*"
              ]
            }
          }
        },
        {
          "name": "SORT_OUT",
          "fields": [
            "jobs['terasort'].hadoopJob.args[2]"
          ],
          "description": "Output directory for terasort",
          "validation": {
            "regex": {
              "regexes": [
                "hdfs:///.*"
              ]
            }
          }
        }
      ],
      "placement": {
        "managedCluster": {
          "clusterName": "to-be-determined",
          "config": {
            "gceClusterConfig": {
              "zoneUri": "us-central1-a"
            }
          }
        }
      }
    }
    

パラメータ化テンプレートにパラメータを渡す

パラメータ化ワークフロー テンプレートを使用するたびに、別のパラメータ値を渡すことができます。テンプレートで定義されている個々のパラメータ値を指定する必要があります。

gcloud コマンド

パラメータ名から値へのマップを gcloud dataproc workflow-templates instantiate コマンドに渡すには、--parameters フラグを使用します。テンプレートで定義されているすべてのパラメータ値を指定する必要があります。ここで指定した値は、テンプレート内で指定されている値よりも優先されます。

パラメータ化されたマネージドクラスタ テンプレートの例

    gcloud dataproc workflow-templates instantiate my-template \
      --parameters CLUSTER=cluster,NUM_ROWS=1000,GEN_OUT=hdfs:///gen_20180601/,SORT_OUT=hdfs:///sort_20180601
    

パラメータ化されたクラスタセレクタ テンプレートの例

    gcloud dataproc workflow-templates instantiate \
      --parameters CLUSTER=my-cluster,NUM_ROWS=10000,OUTPUT_DIR=hdfs://some/dir
        

Rest API

パラメータの names から values への parameters マップを Dataproc の workflowTemplates.instantiate API に渡すことができます。テンプレートで定義されているすべてのパラメータ値を指定する必要があります。ここで指定された値は、テンプレート内で指定されている値よりも優先されます。

例:

    POST https://dataproc.googleapis.com/v1/projects/my-project/regions/us-central1/workflowTemplates/my-template:instantiate
    {
      "parameters": {
        "CLUSTER": "clusterA",
        "NUM_ROWS": "1000",
        "GEN_OUT": "hdfs:///gen_20180601/",
        "SORT_OUT": "hdfs:///sort_20180601/"
      }
    }