워크플로 템플릿의 매개변수화

워크플로 템플릿을 서로 다른 값으로 여러 번 실행할 경우, 템플릿에 매개변수를 정의하면(템플릿의 매개변수화) 워크플로를 매번 편집하지 않아도 됩니다. 템플릿을 실행할 때 매개변수에 서로 다른 값을 전달하면 됩니다.

매개변수화 가능한 필드

다음 Dataproc 워크플로 템플릿 필드는 매개변수화가 가능합니다.

  • 라벨
  • 파일 URI
  • 관리형 클러스터 이름. Dataproc은 사용자 제공 이름을 이름 프리픽스로 사용하고 임의의 문자를 추가하여 고유한 클러스터 이름을 만듭니다. 클러스터는 워크플로가 끝날 때 삭제됩니다.
  • 작업 속성
  • 작업 인수
  • 스크립트 변수(HiveJob, SparkSqlJob, PigJob에서)
  • 기본 클래스(HadoopJob 및 SparkJob에서)
  • 영역(ClusterSelector에서)
  • 마스터 또는 작업자 인스턴스 그룹의 인스턴스 수(numInstances)

매개변수 속성

워크플로 템플릿 매개변수는 다음의 필수 및 선택적 속성을 통해 정의됩니다.

이름(필수)
Unix 스타일의 변수 이름입니다. 나중에 매개변수의 값을 제공할 때 이 이름이 키로 사용됩니다.
필드(필수)
이 매개변수가 대체할 필드의 목록입니다(매개변수화할 수 있는 필드 목록은 매개변수화 가능한 필드 참조). 각 필드는 '필드 경로'로 지정됩니다(필드 경로로 지정하는 데 사용할 구문은 필드 경로 구문 참조). 필드는 한 매개변수의 필드 경로 목록에만 나타날 수 있습니다.
설명(선택사항)
매개변수의 간략한 설명입니다.
검증(선택사항)
매개변수 값을 검증하는 데 사용되는 규칙으로, 다음 중 하나일 수 있습니다.
  1. 허용되는 값 목록
  2. 값이 일치해야 하는 정규 표현식 목록

필드 경로 구문

필드 경로는 구문에서 FieldMask와 비슷합니다. 예를 들어 워크플로 템플릿의 클러스터 선택기에서 영역 필드를 참조하는 필드 경로는 placement.clusterSelector.zone으로 지정됩니다.

필드 경로는 다음 구문을 사용하여 필드를 참조할 수 있습니다.

  • 관리형 클러스터 이름:

    • placement.managedCluster.clusterName

  • 맵에 있는 값을 key로 참조할 수 있습니다. 예를 들면 다음과 같습니다.

    • labels['key']
    • placement.clusterSelector.clusterLabels['key']
    • placement.managedCluster.labels['key']
    • jobs['step-id'].labels['key']

  • 작업 목록에 있는 작업을 step-id로 참조할 수 있습니다.

    • jobs['step-id'].hadoopJob.mainJarFileUri
    • jobs['step-id'].hiveJob.queryFileUri
    • jobs['step-id'].pySparkJob.mainPythonFileUri
    • jobs['step-id'].hadoopJob.jarFileUris[0]
    • jobs['step-id'].hadoopJob.archiveUris[0]
    • jobs['step-id'].hadoopJob.fileUris[0]

    • jobs['step-id'].pySparkJob.pythonFileUris[0]

    • 반복된 필드에 있는 항목을 0부터 시작하는 지수로 참조할 수 있습니다. 예를 들면 다음과 같습니다.

    • jobs['step-id'].sparkJob.args[0]

    • 기타 예시는 다음과 같습니다.

    • jobs['step-id'].hadoopJob.args[0]

    • jobs['step-id'].hadoopJob.mainJarFileUri

    • jobs['step-id'].hadoopJob.properties['key']

    • jobs['step-id'].hiveJob.scriptVariables['key']

    • placement.clusterSelector.zone

맵과 반복된 필드는 전체를 매개변수화할 수 없습니다. 현재는 개별 맵 값과 반복된 필드에 있는 개별 항목만 참조할 수 있습니다. 예를 들어 다음 필드 경로는 유효하지 않습니다.

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

워크플로 템플릿 매개변수화

Dataproc API 또는 Google Cloud CLI로 템플릿 매개변수를 정의하여 워크플로 템플릿을 매개변수화합니다.

gcloud 명령

워크플로 템플릿 YAML 파일을 만들거나, Google Cloud CLI로 내보내고 편집한 후에 Google Cloud CLI로 파일을 가져와서 템플릿을 만들거나 업데이트함으로써 워크플로 템플릿 매개변수를 정의할 수 있습니다. 자세한 내용은 YAML 파일 사용을 참조하세요.

예시 1: 매개변수화된 관리형 클러스터 템플릿 예시

다음은 CLUSTER, NUM_ROWS, GEN_OUT, SORT_OUT의 네 가지 정의된 매개변수가 있는 샘플 teragen-terasort 관리형 클러스터 워크플로 템플릿 YAML 파일입니다. 두 가지 버전이 여기에 나와 있습니다. 하나는 매개변수화하기 이전의 것이고 다른 하나는 이후의 것입니다.

이전

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: 클러스터 선택기 워크플로 템플릿 예시

다음은 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

명령어에 WorkflowTemplate id 또는 정규화된 템플릿 리소스 name('projects/projectId/regions/region/workflowTemplates/template_id')를 전달할 수 있습니다. 템플릿 이름이 동일한 템플릿 리소스가 존재하면 덮어써지고(업데이트되고) 버전 번호가 증분됩니다. 동일한 이름의 템플릿이 없으면 새로 생성됩니다.

REST API

workflowTemplates.create 또는 workflowTemplates.update API 요청에서 하나 이상의 WorkflowTemplate.parameters를 정의할 수 있습니다.

다음은 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 명령

--parameters 플래그를 사용하여 매개변수 names와 values를 연결하는 맵을 gcloud dataproc workflow-templates instantiate 명령어에 전달할 수 있습니다. 템플릿에 정의된 모든 매개변수 값을 제공해야 합니다. 제공된 값은 템플릿에 지정된 값을 재정의합니다.

매개변수화된 관리형 클러스터 템플릿 예시

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