Parametrización de plantillas de flujo de trabajo

Si tu plantilla de flujo de trabajo se ejecutará varias veces con diferentes valores, puedes evitar editar el flujo de trabajo cada vez mediante la definición de los parámetros en la plantilla (parametrizar la plantilla). Luego, puedes pasar diferentes valores para los parámetros cada vez que ejecutes la plantilla.

Campos parametrizables

Los siguientes campos de la plantilla de flujo de trabajo de Dataproc se pueden parametrizar:

  • Labels
  • URI de archivos
  • Nombre del clúster administrado. Dataproc usará el nombre proporcionado por el usuario como prefijo del nombre y agregará caracteres aleatorios para crear un nombre de clúster único. El clúster se borra al final del flujo de trabajo.
  • Propiedades del trabajo
  • Argumentos del trabajo
  • Variables de la secuencia de comandos (en HiveJob, SparkSqlJob y PigJob)
  • Clase principal (en HadoopJob y SparkJob)
  • Zona (en ClusterSelector)
  • Cantidad de instancias (numInstances) en un grupo de instancias principal o trabajador

Atributos de parámetros

Los parámetros de plantillas de flujo de trabajo se definen con los siguientes atributos obligatorios y opcionales:

El nombre es obligatorio
Es un nombre de variable de estilo Unix. Este nombre se usará como clave cuando se proporcione un valor para el parámetro más adelante.
Campos obligatorios
Una lista de campos que este parámetro reemplazará (consulta Campos parametrizables para ver una lista de campos que se pueden parametrizar). Cada campo se especifica como una "ruta de campo" (consulta Sintaxis de ruta de campo para obtener la sintaxis que se usa para especificar una ruta de campo). Ten en cuenta que un campo puede aparecer en la lista de rutas de campos de un parámetro como máximo.
Descripción (opcional)
Descripción breve del parámetro
validación (opcional)
Reglas que se usan para validar un valor de parámetro, que puede ser uno de los siguientes:
  1. una lista de valores permitidos
  2. una lista de expresiones regulares con las que un valor debe coincidir.

Sintaxis de ruta del campo

Una ruta de campo es similar en sintaxis a una FieldMask. Por ejemplo, una ruta de campo que hace referencia al campo de zona del selector de clústeres de una plantilla de flujo de trabajo se puede especificar como placement.clusterSelector.zone.

Las rutas de los campos pueden hacer referencia a los campos mediante el uso de la siguiente sintaxis:

  • Nombre del clúster administrado:

    • placement.managedCluster.clusterName
  • Se puede hacer referencia a los valores de los mapas por clave, por ejemplo:

    • labels['key']
    • placement.clusterSelector.clusterLabels['key']
    • placement.managedCluster.labels['key']
    • jobs['step-id'].labels['key']
  • Se puede hacer referencia a los trabajos de la lista de trabajos por 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]

    • Un índice basado en cero puede hacer referencia a los elementos en campos repetidos, por ejemplo:

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

    • Otros ejemplos

    • 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

Los mapas y los campos repetidos no se pueden parametrizar por completo: solo se puede hacer referencia a valores de mapas individuales y elementos individuales en campos repetidos. Por ejemplo, las siguientes rutas de campo no son válidas:

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

Parametriza una plantilla de flujo de trabajo

Parametriza una plantilla de flujo de trabajo, define parámetros de plantilla con la API de Dataproc o la herramienta de línea de comandos de gcloud.

Comando de gcloud

Para definir los parámetros de la plantilla de flujo de trabajo, debes crear o exportar la herramienta de línea de comandos de gcloud y editar un archivo YAML de una plantilla de flujo de trabajo. Luego, debes importar el archivo con la herramienta de línea de comandos de gcloud a fin de crear o actualizar la plantilla. Consulta Usa archivos YAML para obtener más información.

Ejemplo 1: Ejemplo de plantilla de clúster administrado parametrizada

El siguiente es un archivo YAML de plantilla de flujo de trabajo de clúster administrado teragen-terasort de muestra con cuatro parámetros definidos: CLUSTER, NUM_ROWS, GEN_OUT y SORT_OUT. Se enumeran dos versiones: una ANTES y la otra DESPUÉS de la parametrización.

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

Después

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

Ejemplo 2: Ejemplo de plantilla de flujo de trabajo del selector de clústeres

El siguiente es un archivo YAML de plantilla de flujo de trabajo de selector de clústeres teragen-terasort de muestra con tres parámetros definidos: CLUSTER, NUM_ROWS y 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]

Después de crear o editar un archivo YAML que defina una plantilla de flujo de trabajo con parámetros de plantilla, usa el siguiente comando de gcloud para crear o actualizar la plantilla con parámetros.

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

Puedes pasar el id de WorkflowTemplate o el name del recurso de plantilla completamente calificado ("projects/projectId/regions/region/workflowTemplates/template_id") al comando. Si existe un recurso de plantilla con el mismo nombre de plantilla, se reemplazará (actualizará) y se aumentará el número de versión. Si no existe una plantilla con el mismo nombre, esta se creará.

API de REST

Puedes definir uno o más WorkflowTemplate.parameters en una solicitud a la API workflowTemplates.create o workflowTemplates.update.

A continuación, se muestra una solicitud workflowTemplates.create de muestra para crear una plantilla de flujo de trabajo teragen-terasort con cuatro parámetros definidos: CLUSTER, NUM_ROWS, GEN_OUT y 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"
        }
      }
    }
  }
}

Pasa parámetros a una plantilla con parámetros

Puedes pasar un conjunto diferente de valores de parámetros cada vez que ejecutas una plantilla de flujo de trabajo parametrizada. Debes proporcionar un valor para cada parámetro definido en la plantilla.

Comando de gcloud

Puedes pasar un mapa de nombres de parámetros a valores al comando gcloud dataproc workflow-templates instantiate con la marca --parameters. Se deben proporcionar todos los valores de parámetro definidos en la plantilla. Los valores proporcionados anularán los valores especificados en la plantilla.

Ejemplo de plantilla de clúster administrado parametrizada

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

Ejemplo de plantilla del selector de clústeres parametrizado

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

API de REST

Puedes pasar un mapa de parameters del parámetro names a values para la API de Dataproc workflowTemplates.instantiate. Se deben proporcionar todos los valores de parámetros definidos en la plantilla. Los valores proporcionados anularán los valores especificados en la plantilla.

.

Ejemplo:

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