Parametrización de plantillas de flujo de trabajo

Si su plantilla de flujo de trabajo se ejecutará varias veces con valores diferentes, puede evitar tener que editar el flujo de trabajo definiendo parámetros en la plantilla (parametrizando la plantilla). Luego, puedes pasar valores diferentes para los parámetros cada vez que ejecutes la plantilla.

Campos con parámetros

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

  • Labels
  • URI de archivo
  • Nombre del clúster administrado. Dataproc usará el nombre proporcionado por el usuario como el 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)
  • Número de instancias (numInstances) en un grupo de instancias principal o trabajador.

Atributos del parámetro

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

El nombre es obligatorio
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 reemplazará este parámetro (consulta Campos parametrizables para ver una lista de campos que se pueden parametrizar). Cada campo se especifica como "ruta de campo" (consulta Sintaxis de ruta de campo para que la sintaxis use para especificar una ruta de campo). Ten en cuenta que un campo puede aparecer en la lista de rutas de campo de un parámetro como máximo.
Descripción (opcional)
Descripción breve del parámetro
validación (opcional)
Reglas utilizadas 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 que un valor debe coincidir.

Sintaxis de ruta de 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úster de una plantilla de flujo de trabajo se especificaría como placement.clusterSelector.zone.

Las rutas de campo pueden hacer referencia a los campos con la siguiente sintaxis:

  • Nombre del clúster administrado:

    • ubicación.managedCluster.clusterName
  • Se puede hacer referencia a los valores en 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 paso-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]

    • Se puede hacer referencia a los elementos en los campos repetidos mediante un índice basado en cero, 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 parámetros en su totalidad: actualmente, 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

Puede parametrizar una plantilla de flujo de trabajo definiendo 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, crea o exporta con la herramienta de línea de comandos de gcloud y edita un archivo YAML de plantilla de flujo de trabajo y, luego, importa el archivo con la herramienta de línea de comandos de gcloud para crear o actualizar la plantilla. . Consulta Usa archivos YAML para obtener más información.

Ejemplo 1: Ejemplo de plantilla de clúster administrado con parámetros

El siguiente es un archivo YAML de plantilla de flujo de trabajo de clúster administrado de muestra con cuatro parámetros definidos: CLUSTER, NUM_ROWS, Gen_OUT y SORT_OUT. Se enumeran dos versiones: una parametrización BEFORE y la otra AFTER.

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 clúster de flujo de trabajo de muestra teragen-terasort 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 importar o actualizar la plantilla con parámetros.

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

Puedes pasar el id de WorkflowTemplate o el valor de 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 incrementará su 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 de 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, Gene_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"
            }
          }
        }
      }
    }
    

Cómo pasar parámetros a una plantilla con parámetros

Puede pasar un conjunto diferente de valores de parámetros cada vez que ejecute 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 los valores al comando gcloud dataproc workflow-template instantiate con la marca --parameters. 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 de plantilla de clúster administrado con parámetros

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

Ejemplo de plantilla de selector de clúster parametrizada

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

API de REST

Puede pasar un parameters mapa del parámetro names a values a 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/"
      }
    }