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

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

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

パラメータ化可能な 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 \
    --region=region \
    --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 \
    --region=region \
    --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/"
  }
}