Parametrización de plantillas de flujo de trabajo

Si tu plantilla de flujo de trabajo se va a ejecutar varias veces con valores diferentes, puedes evitar tener que editar el flujo de trabajo cada vez si defines parámetros en la plantilla (parametrización de la plantilla). Luego, puedes pasar diferentes valores para los parámetros cada vez que ejecutas la plantilla.

Puedes agregar parámetros a tu plantilla de flujo de trabajo cuando creas o actualizas 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 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

Parametrizar las etiquetas del selector de clústeres te permite elegir el clúster donde se ejecutará el flujo de trabajo cada vez que ejecutes el flujo de trabajo (consulta Usa selectores de clúster con flujos de trabajo).

Atributos de los parámetros

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 una 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ú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 mediante la siguiente sintaxis:

• Nombre del clúster administrado:

  • placement.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 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 en su totalidad: por el momento, solo se puede hacer referencia a los valores de mapa individuales y a los elementos individuales en los 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 mediante la definición de parámetros de plantilla con la API de Dataproc o Google Cloud CLI.

Comando de gcloud

Puedes definir parámetros de plantilla de flujo de trabajo si creas o exportas con Google Cloud CLI y editas un archivo YAML de plantilla de flujo de trabajo y, luego, importas el archivo con Google Cloud CLI para crear o actualizar la plantilla. Consulta Cómo usar 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, se reemplazará (actualizará) y se aumentará el número de la versión. Si no existe una plantilla con el mismo nombre, esta se creará.

Por el momento, no puedes usar Google Cloud CLI para ejecutar un flujo de trabajo directamente desde un archivo YAML que define una plantilla de flujo de trabajo con parámetros (consulta Crea una instancia de flujo de trabajo con un archivo YAML). Primero debes importar el archivo YAML y, luego, pasar los parámetros a la plantilla de flujo de trabajo cuando crees una instancia como se explica en este y en las siguientes subsecciones.

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 ejecutes una plantilla de flujo de trabajo con parámetros. 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 del comando gcloud dataproc workflow-templates 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 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 parameters del parámetro names a values a la API deworkflowTemplates.instantiate de Dataproc. Se deben proporcionar todos los valores de parámetros definidos en la plantilla. Los valores proporcionados anularán los valores especificados en la plantilla.

No puedes pasar parámetros a una plantilla de flujo de trabajo con la API workflowTemplates.instantiateinline.

.

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