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 cada vez definiendo parámetros en la plantilla (parametrización de la plantilla). Luego, puede pasar valores diferentes para los parámetros cada vez que ejecute la plantilla.

Campos parametrizables

Se pueden parametrizar los siguientes campos de la plantilla de flujo de trabajo de Dataproc:

  • Etiquetas
  • URI de archivos
  • Nombre del clúster administrado . Dataproc utilizará 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 elimina al final del flujo de trabajo.
  • Propiedades del trabajo
  • Argumentos laborales
  • Variables de script (en HiveJob, SparkSqlJob y PigJob)
  • Clase principal (en HadoopJob y SparkJob)
  • Zona (en ClusterSelector)
  • Número de instancias ( numInstances ) en un grupo de instancias maestro o trabajador.

Atributos de parámetros

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

nombre (requerido)
Un nombre de variable de estilo Unix. Este nombre se utilizará como clave cuando se proporcione un valor para el parámetro más adelante.
campos (requeridos)
Una lista de campos que este parámetro reemplazará (consulte Campos parametrizables para obtener una lista de campos que se pueden parametrizar). Cada campo se especifica como una "ruta de campo" (consulte Sintaxis de ruta de campo para conocer la sintaxis que se utilizará para especificar una ruta de campo). Tenga en cuenta que se permite que un campo aparezca como máximo en la lista de rutas de campo de un parámetro.
descripción (opcional)
Breve descripción del parámetro.
validación (opcional)
Reglas utilizadas para validar el valor de un parámetro, que puede ser uno de:
  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 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 placement.clusterSelector.zone .

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

  • Nombre del clúster administrado:

    • colocación.managedCluster.clusterName

  • Se puede hacer referencia a los valores en los mapas mediante clave, por ejemplo:

    • etiquetas ['clave']
    • colocación.clusterSelector.clusterLabels['clave']
    • colocación.managedCluster.labels['clave']
    • trabajos['id-paso'].etiquetas['clave']

  • Se puede hacer referencia a los trabajos en la lista de trabajos mediante ID de paso.

    • trabajos['id-paso'].hadoopJob.mainJarFileUri
    • trabajos['id-paso'].hiveJob.queryFileUri
    • trabajos['id-paso'].pySparkJob.mainPythonFileUri
    • trabajos['id-paso'].hadoopJob.jarFileUris[0]
    • trabajos['id-paso'].hadoopJob.archiveUris[0]
    • trabajos['id-paso'].hadoopJob.fileUris[0]

    • trabajos['id-paso'].pySparkJob.pythonFileUris[0]

    • Se puede hacer referencia a los elementos en campos repetidos mediante un índice de base cero, por ejemplo:

    • trabajos['id-paso'].sparkJob.args[0]

    • Otros ejemplos:

    • trabajos['id-paso'].hadoopJob.args[0]

    • trabajos['id-paso'].hadoopJob.mainJarFileUri

    • trabajos['id-paso'].hadoopJob.properties['clave']

    • trabajos['id-paso'].hiveJob.scriptVariables['clave']

    • colocación.clusterSelector.zone

Los mapas y los campos repetidos no se pueden parametrizar 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

Parametrización de una plantilla de flujo de trabajo

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

Comando gcloud

Puede 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 y luego importando el archivo con la CLI de Google Cloud para crear o actualizar la plantilla. Consulte Uso de archivos YAML para obtener más información.

Ejemplo 1: ejemplo de plantilla de clúster administrado parametrizado

El siguiente es un archivo YAML de plantilla de flujo de trabajo de clúster administrado de teragen-terasort con cuatro parámetros definidos: CLUSTER, NUM_ROWS, GEN_OUT y SORT_OUT. Se enumeran 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 del selector de clústeres

El siguiente es un archivo YAML de plantilla de flujo de trabajo de selector de clúster teragen-terasort parametrizado 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 define una plantilla de flujo de trabajo con parámetros de plantilla, use 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

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

API de descanso

Puede definir uno o más parámetros WorkflowTemplate.en una solicitud de API flowTemplates.create o flowTemplates.update .

A continuación se muestra un ejemplo de solicitud workflowTemplates.create 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"
        }
      }
    }
  }
}

Pasar parámetros a una plantilla parametrizada

Puede pasar un conjunto diferente de valores de parámetros cada vez que ejecute 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 de creación de instancias de plantillas de flujo de trabajo de gcloud dataproc 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 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

Ejemplo de plantilla de selector de clúster parametrizado

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

API de descanso

Puede pasar un mapa de parameters de names de parámetros a values a la API flowTemplates.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.

.

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