Parametrização de modelos de fluxo de trabalho

Ao executar um modelo do fluxo de trabalho com diferentes valores, é possível definir parâmetros do modelo para não ter de editar o fluxo de trabalho a cada execução. Esse processo é chamado de parametrização do modelo. Dessa forma, é possível passar diferentes valores para os parâmetros a cada execução do modelo.

Campos parametrizáveis

Estes são os campos de modelo do fluxo de trabalho do Dataproc que podem ser parametrizados:

  • Rótulos
  • URIs de arquivo
  • Nome do cluster gerenciado. O Dataproc usará o nome fornecido pelo usuário como prefixo do nome e anexará caracteres aleatórios para criar um nome de cluster exclusivo. O cluster é excluído no final do fluxo de trabalho.
  • Propriedades de job
  • Argumentos de job
  • Variáveis de script (no HiveJob, SparkSqlJob e PigJob)
  • Classe principal (no HadoopJob e no SparkJob)
  • Zona (no ClusterSelector)
  • Número de instâncias (numInstances) em um grupo de instâncias mestre ou de trabalho.

Atributos do parâmetro

Os parâmetros do modelo do fluxo de trabalho são definidos com estes atributos obrigatórios e opcionais:

Nome (obrigatório)
Um nome variável no estilo unix. Esse nome é usado como chave ao fornecer um valor para o parâmetro posteriormente.
Campos (obrigatório)
Uma lista de campos que esse parâmetro substituirá. Para uma lista de campos que podem ser parametrizados, consulte Campos parametrizáveis. Cada campo é especificado como um "caminho do campo". Para a sintaxe usada para especificar um caminho do campo, consulte Sintaxe do caminho do campo. Observe que um campo pode aparecer em no máximo uma lista de caminhos do campo de um parâmetro.
Descrição (opcional)
Breve descrição do parâmetro.
Validação (opcional)
Regras usadas para validar um valor de parâmetro, que pode ser uma das seguintes:
  1. uma lista de valores permitidos
  2. uma lista de expressões regulares que um valor precisa corresponder.

Sintaxe do caminho do campo

Um caminho do campo tem sintaxe semelhante a usada em FieldMask. Por exemplo, um caminho de campo que faça referência ao campo da zona do seletor de cluster de um modelo de fluxo de trabalho seria especificado como placement.clusterSelector.zone.

Os caminhos de campo podem fazer referência a campos usando a seguinte sintaxe:

  • Nome do cluster gerenciado:

    • placement.managedCluster.clusterName

  • Valores em mapas são referenciados pela chave. Por exemplo:

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

  • Jobs na lista de jobs são referenciados pelo código de etapa (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]

    • Itens em campos repetidos são referenciados por um índice começando em zero.Por exemplo:

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

    • Outros exemplos

    • 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

Mapas e campos repetidos não podem ser totalmente parametrizados. Atualmente, apenas valores de mapas individuais e itens individuais em campos repetidos podem ser referenciados. Por exemplo, estes caminhos do campo são inválidos:

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

Como parametrizar um modelo do fluxo de trabalho

É possível parametrizar um modelo de fluxo de trabalho definindo os parâmetros do modelo com a API Dataproc ou a Google Cloud CLI.

Comando gcloud

É possível definir parâmetros do modelo de fluxo de trabalho criando ou exportando com a Google Cloud CLI e editando um arquivo YAML do modelo de fluxo de trabalho e importando o arquivo com a Google Cloud CLI para criar ou atualizar o modelo. Para mais informações, consulte Como usar arquivos YAML.

Exemplo 1: exemplo de modelo de cluster gerenciado parametrizado

Este é um arquivo YAML de modelo defluxo de trabalho de cluster gerenciado teragen-terasort com quatro parâmetros definidos: CLUSTER, NUM_ROWS, GEN_OUT, and SORT_OUT. Duas versões estão listadas: uma ANTES e a outra APÓS a parametrização.

Antes

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

Depois

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:///.*

Exemplo 2: exemplo de modelo de fluxo de trabalho do seletor de cluster

Este é uma amostra parametrizada teragen-terasort de um arquivo YAML do modelo de fluxo de trabalho do seletor de cluster com três parâmetros definidos: CLUSTER, NUM_ROWS e OUTPUT_DIR.

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]

Após criar ou editar um arquivo YAML que define um modelo de fluxo de trabalho com parâmetros de modelo, use o seguinte comando gcloud para importar o arquivo YAML para criar ou atualizar o modelo parametrizado.

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

Você pode passar o WorkflowTemplate id ou o recurso de modelo totalmente qualificado name ("projects/projectId/region/region/workflowTemplates/template_id") ao comando. Se um recurso do modelo tiver o mesmo nome de outro modelo, este será substituído (atualizado) e seu número de versão será incrementado. Se não existirem dois modelos com o mesmo nome, um modelo será criado.

API REST

É possível definir um ou mais WorkflowTemplate.parameters usando as solicitações de API workflowTemplates.create ou workflowTemplates.update.

Veja a seguir um exemplo de solicitação workflowTemplates.create para criar um modelo de fluxo de trabalho teragen-terasort com quatro parâmetros definidos: CLUSTER, NUM_ROWS, GEN_OUT, and SORT_OUT.

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

Como passar parâmetros para um modelo parametrizado

É possível passar um conjunto diferente de valores de parâmetro a cada vez que você executar um modelo do fluxo de trabalho parametrizado. É necessário fornecer um valor para cada parâmetro definido no modelo.

Comando gcloud

É possível passar um mapa de nomes de parâmetros para valores com o comandogcloud dataproc workflow-models instantiate com a sinalização --parameters. Todos os valores de parâmetro definidos no modelo precisam ser fornecidos. Os valores fornecidos substituirão os valores especificados no modelo.

Exemplo de modelo de cluster gerenciado parametrizado

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

Exemplo de modelo de seletor de cluster parametrizado

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

API REST

Você pode passar um mapa parameters do parâmetro names para values para a API workflowTemplates.instantiate do Dataproc. Todos os valores de parâmetro definidos no modelo precisam ser fornecidos. Os valores fornecidos substituirão os valores especificados no modelo.

.

Exemplo:

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