Parametrizzazione dei modelli di workflow

Se il modello di workflow verrà eseguito più volte con valori diversi, puoi evitare di dover modificare il workflow ogni volta definendo i parametri nel modello (parametrizzando il modello). Poi, puoi passare valori diversi per i parametri ogni volta che esegui il modello.

Campi parametrizzabili

I seguenti campi del modello di workflow Dataproc possono essere parametrizzati:

  • Etichette
  • URI file
  • Nome del cluster gestito. Dataproc utilizzerà il nome fornito dall'utente come prefisso del nome e aggiungerà caratteri casuali per creare un nome del cluster univoco. Il cluster viene eliminato al termine del flusso di lavoro.
  • Proprietà del job
  • Argomenti del job
  • Variabili script (in HiveJob, SparkSqlJob e PigJob)
  • Classe principale (in HadoopJob e SparkJob)
  • Zona (in ClusterSelector)
  • Numero di istanze (numInstances) in un gruppo di istanze master o worker.

Attributi dei parametri

I parametri del modello di workflow sono definiti con i seguenti attributi obbligatori e facoltativi:

name (obbligatorio)
Un nome di variabile in stile Unix. Questo nome verrà utilizzato come chiave quando fornirai un valore per il parametro in un secondo momento.
campi (obbligatori)
Un elenco di campi che questo parametro sostituirà (vedi Campi parametrizzabili per un elenco di campi che possono essere parametrizzati). Ogni campo viene specificato come "percorso del campo" (vedi Sintassi del percorso del campo per la sintassi da utilizzare per specificare un percorso del campo). Tieni presente che un campo può essere visualizzato nell'elenco dei percorsi dei campi di al massimo un parametro.
descrizione (facoltativa)
Breve descrizione del parametro.
validation (facoltativo)
Regole utilizzate per convalidare un valore parametro, che può essere uno dei seguenti:
  1. un elenco di valori consentiti
  2. un elenco di espressioni regolari a cui deve corrispondere un valore.

Sintassi del percorso del campo

Un percorso del campo ha una sintassi simile a una FieldMask. Ad esempio, un percorso del campo che fa riferimento al campo della zona del selettore del cluster di un modello di workflow verrebbe specificato come placement.clusterSelector.zone.

I percorsi dei campi possono fare riferimento ai campi utilizzando la seguente sintassi:

  • Nome del cluster gestito:

    • placement.managedCluster.clusterName

  • È possibile fare riferimento ai valori nelle mappe in base alla chiave, ad esempio:

    • labels['key']
    • placement.clusterSelector.clusterLabels['key']
    • placement.managedCluster.labels['key']
    • jobs['step-id'].labels['key']

  • È possibile fare riferimento ai job nell'elenco dei job in base all'ID passaggio.

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

    • È possibile fare riferimento agli elementi nei campi ripetuti tramite un indice basato su zero, ad esempio:

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

    • Altri esempi:

    • 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

Non puoi parametrizzare le mappe e i campi ripetuti nella loro interezza. È possibile fare riferimento solo a singoli valori della mappa e a singoli elementi nei campi ripetuti. Ad esempio, i seguenti percorsi dei campi non sono validi:

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

Parametrizzare un modello di workflow

Puoi parametrizzare un modello di workflow definendo i parametri del modello con l'API Dataproc o Google Cloud CLI.

Comando g-cloud

Puoi definire i parametri del modello di flusso di lavoro creando o esportando con Google Cloud CLI e modificando un file YAML del modello di flusso di lavoro, quindi importando il file con Google Cloud CLI per creare o aggiornare il modello. Per ulteriori informazioni, consulta Utilizzo di file YAML.

Esempio 1: esempio di modello di cluster gestito con parametri

Di seguito è riportato un file YAML di modello di workflow managed-cluster teragen-terasort di esempio con quattro parametri definiti: CLUSTER, NUM_ROWS, GEN_OUT e SORT_OUT. Sono elencate due versioni: una PRIMA e l'altra DOPO la parametrizzazione.

Prima

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

Dopo

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

Esempio 2: esempio di modello di flusso di lavoro del selettore di cluster

Di seguito è riportato un esempio parametrizzato di teragen-terasort cluster-selector workflow file YAML del modello con tre parametri definiti: CLUSTER, NUM_ROWS e 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]

Dopo aver creato o modificato un file YAML che definisce un modello di flusso di lavoro con parametri del modello, utilizza il seguente comando gcloud per importare il file YAML per creare o aggiornare il modello con parametri.

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

Puoi trasmettere al comando WorkflowTemplate id o la risorsa modello completa name ("projects/projectId/regions/region/workflowTemplates/template_id"). Se esiste una risorsa modello con lo stesso nome, questa verrà sovrascritta (aggiornata) e il relativo numero di versione verrà incrementato. Se non esiste un modello con lo stesso nome, verrà creato.

API Rest

Puoi definire uno o più WorkflowTemplate.parameters in una richiesta API workflowTemplates.create o workflowTemplates.update.

Di seguito è riportato un esempio di richiesta workflowTemplates.create per creare un modello di workflow teragen-terasort con quattro parametri definiti: CLUSTER, NUM_ROWS, GEN_OUT e 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"
        }
      }
    }
  }
}

Passare parametri a un modello parametrizzato

Puoi trasmettere un insieme diverso di valori dei parametri ogni volta che esegui un modello di workflow parametrizzato. Devi fornire un valore per ogni parametro definito nel modello.

Comando gcloud

Puoi passare una mappa di nomi di parametri ai valori al comando gcloud dataproc workflow-templates instantiate con il flag --parameters. Devono essere forniti tutti i valori dei parametri definiti nel modello. I valori forniti sostituiranno quelli specificati nel modello.

Esempio di modello di cluster gestito con parametri

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

Esempio di modello di selettore di cluster parametrizzato

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

API Rest

Puoi trasmettere una mappa parameters del parametro names a values all'API workflowTemplates.instantiate di Dataproc. Tutti i valori dei parametri definiti nel modello devono essere forniti. I valori forniti sostituiranno quelli specificati nel modello.

Esempio:

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