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 definiendo parámetros en la plantilla (parametrizando la plantilla). Después, puedes asignar valores diferentes a 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:

  • Etiquetas
  • URIs de archivos
  • Nombre del clúster gestionado. Dataproc usará el nombre proporcionado por el usuario como prefijo y añadirá caracteres aleatorios para crear un nombre de clúster único. El clúster se elimina al final del flujo de trabajo.
  • Propiedades de la tarea
  • Argumentos de las tareas
  • Variables de secuencias de comandos (en HiveJob, SparkSqlJob y PigJob)
  • Clase principal (en HadoopJob y SparkJob)
  • Zona (en ClusterSelector)
  • Número de instancias (numInstances) de un grupo de instancias maestras o de trabajo.

Atributos de parámetros

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

name (obligatorio)
Nombre de variable de estilo Unix. Este nombre se usará como clave cuando proporcione un valor para el parámetro más adelante.
Campos (obligatorio)
Lista de campos que sustituirá este parámetro (consulta la sección Campos parametrizables para ver una lista de los campos que se pueden parametrizar). Cada campo se especifica como una "ruta de campo" (consulta la sintaxis de ruta de campo para ver la sintaxis que se debe usar para especificar una ruta de campo). Ten en cuenta que un campo solo puede aparecer en la lista de rutas de campo de un parámetro.
Descripción (opcional)
Breve descripción del parámetro.
validation (opcional)
Reglas que se usan para validar el valor de un parámetro. Puede ser uno de los siguientes:
  1. una lista de valores permitidos
  2. Una lista de expresiones regulares con las que debe coincidir un valor.

Sintaxis de la ruta del campo

La sintaxis de una ruta de campo es similar a la de un FieldMask. Por ejemplo, una ruta de campo que haga referencia al campo de zona de un 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 campos mediante la siguiente sintaxis:

  • Nombre del clúster gestionado:

    • 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 las tareas de la lista de tareas mediante el ID de paso.

    • 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 de 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

No puedes parametrizar mapas ni campos repetidos en su totalidad. Solo se pueden hacer referencias a valores de mapas individuales y a elementos individuales de campos repetidos. Por ejemplo, las siguientes rutas de campo no son válidas:

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

Parametrizar una plantilla de flujo de trabajo

Para parametrizar una plantilla de flujo de trabajo, define parámetros de plantilla con la API de Dataproc o la CLI de Google Cloud.

Comando gcloud

Puedes definir los parámetros de la plantilla de flujo de trabajo creando o exportando con la CLI de Google Cloud y editando un archivo YAML de plantilla de flujo de trabajo. Después, importa el archivo con la CLI de Google Cloud para crear o actualizar la plantilla. Consulta Usar archivos YAML para obtener más información.

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

A continuación, se muestra un archivo YAML de plantilla de flujo de trabajo de clúster gestionado de teragen-terasort con cuatro parámetros definidos: CLUSTER, NUM_ROWS, GEN_OUT y SORT_OUT. Se muestran dos versiones: una ANTES y 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 de selector de clústeres

A continuación, se muestra un ejemplo parametrizado de archivo YAML de plantilla de flujo de trabajo de selector de clústeres 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 el archivo YAML y crear o actualizar la plantilla parametrizada.

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

Puedes pasar el WorkflowTemplate id o el recurso de plantilla completo name ("projects/projectId/regions/region/workflowTemplates/template_id") al comando. Si ya existe un recurso de plantilla con el mismo nombre, se sobrescribirá (se actualizará) y se incrementará su número de versión. Si no existe una plantilla con el mismo nombre, se creará.

API REST

Puede definir uno o varios WorkflowTemplate.parameters en una solicitud de la API workflowTemplates.create o workflowTemplates.update.

A continuación, se muestra una solicitud workflowTemplates.create de ejemplo para crear una plantilla de flujo de trabajo de 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"
        }
      }
    }
  }
}

Transferir parámetros a una plantilla parametrizada

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

Comando 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 los parámetros definidos en la plantilla. Los valores proporcionados anularán los valores especificados en la plantilla.

Ejemplo de plantilla de clúster gestionado con parámetros

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 de selector de clústeres parametrizado

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

API REST

Puedes transferir un parameters mapa de parámetros names a values a la API workflowTemplates.instantiate de Dataproc. Deben proporcionarse todos los valores de los parámetros definidos en la plantilla. Los valores proporcionados sobrescribirá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/"
  }
}