Paramétrer des modèles de workflow

Si vous exécutez un modèle de workflow plusieurs fois avec des valeurs différentes, il est utile d'éviter de modifier le modèle de workflow à chaque fois en définissant certains paramètres du modèle (paramétrage du modèle). Vous pourrez ensuite transmettre différentes valeurs pour les paramètres à chaque fois que vous exécutez le modèle.

Champs paramétrables

Les champs de modèle de workflow Dataproc suivants peuvent être paramétrés :

  • Labels
  • URI de fichier
  • Nom du cluster géré. Dataproc utilise le nom fourni par l'utilisateur comme préfixe de nom et ajoute des caractères aléatoires pour créer un nom de cluster unique. Le cluster est supprimé à la fin du workflow.
  • Propriétés de la tâche
  • Arguments de la tâche
  • Variables de script (dans HiveJob, SparkSqlJob et PigJob)
  • Classe principale (dans HadoopJob et SparkJob)
  • Zone (dans ClusterSelector)
  • Nombre d'instances (numInstances) dans un groupe d'instances maître ou de nœud de calcul.

Attributs des paramètres

Les paramètres des modèles de flux de travail sont définis avec les attributs obligatoires et facultatifs suivants :

Nom (obligatoire)
Nom de variable de style unix. Ce nom fera office de clé au moment de fournir une valeur pour le paramètre.
Champs (obligatoires)
Liste des champs que ce paramètre pourra remplacer (consultez la section Champs paramétrables pour obtenir une liste des champs pouvant être paramétrés). Chaque champ est spécifié en tant que "chemin d'accès de champ" (consultez la section Syntaxe d'un chemin d'accès de champ pour connaître la syntaxe permettant de spécifier un chemin d'accès de champ). Veuillez prendre en compte qu'un champ est autorisé à apparaître dans une liste au maximum de chemins d'accès de champ d'un paramètre.
Description (facultative)
Brève description du paramètre.
Validation (facultative)
Règles utilisées pour valider une valeur de paramètre, parmi l'une des règles suivantes :
  1. une liste de valeurs autorisées,
  2. une liste d'expressions régulières auxquelles une valeur doit correspondre.

Syntaxe d'un chemin d'accès de champ

La syntaxe d'un chemin d'accès de champ est semblable à celle d'un FieldMask. Par exemple, un chemin d'accès de champ faisant référence au champ de zone du sélecteur de cluster d'un modèle de workflow serait spécifié comme placement.clusterSelector.zone.

Les chemins d'accès de champ peuvent référencer des champs à l'aide de la syntaxe suivante :

  • Nom du cluster géré :

    • placement.managedCluster.clusterName

  • Les valeurs affichées dans les maps peuvent être référencées par key (clé). Exemple :

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

  • Les tâches de la liste des tâches peuvent être référencées par step-id (ID de l'étape).

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

    • Les éléments de champs répétés peuvent être référencés par un index basé sur zéro. Exemple :

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

    • Autres exemples :

    • 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

Les cartes et les champs répétés ne peuvent pas être paramétrés dans leur intégralité. À l'heure actuelle, il n'est possible de référencer que les valeurs de carte individuelles et les éléments individuels de champs répétés. Par exemple, les chemins d'accès de champ suivants ne sont pas valides :

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

Paramétrer un modèle de flux de travail

Vous paramétrez un modèle de workflow en définissant des paramètres de modèle avec l'API Dataproc ou la Google Cloud CLI.

Commande gcloud

Vous pouvez définir des paramètres de modèle de workflow en créant ou en exportant un fichier YAML de modèle de workflow à l'aide de la Google Cloud CLI et en le modifiant, puis en important le fichier à l'aide de la Google Cloud CLI pour créer ou mettre à jour le modèle. Consultez la section Utiliser les fichiers YAML pour en savoir plus.

Exemple 1 : Exemple de modèle de cluster géré paramétré

L'exemple ci-dessous illustre un fichier YAML de modèle de workflow de cluster géré teragen-terasort avec quatre paramètres définis : CLUSTER, NUM_ROWS, GEN_OUT et SORT_OUT. Deux versions sont affichées : l'une AVANT le paramétrage et l'autre APRÈS.

Avant

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

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

Example 2 : Exemple de modèle de flux de travail de sélecteur de cluster

L'exemple ci-dessous illustre un fichier YAML de modèle de workflow de sélecteur de cluster teragen-terasort avec trois paramètres définis : CLUSTER, NUM_ROWS et 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]

Après avoir créé ou modifié un fichier YAML définissant un modèle de flux de travail avec des paramètres de modèle, utilisez la commande gcloud suivante pour importer le fichier YAML afin de créer ou de mettre à jour le modèle paramétré :

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

Vous pouvez transmettre le modèle de workflow id ou la ressource de modèle complet name ("projects/projectId/régions/region/workflowTemplates/template_id"). ) à la commande. Si la ressource de modèle porte le même nom qu'un modèle existant, elle sera écrasée (mise à jour) et son numéro de version sera incrémenté. S'il n'existe aucun nom de modèle similaire, le modèle sera créé.

API REST

Vous pouvez définir un ou plusieurs WorkflowTemplate.parameters dans workflowTemplates.create ou workflowTemplates.update.

Vous trouverez ci-dessous un exemple de requête workflowTemplates.create de création d'un modèle de workflow teragen-terasort avec quatre paramètres définis : CLUSTER, NUM_ROWS, GEN_OUT et 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"
        }
      }
    }
  }
}

Transmettre des paramètres à un modèle paramétré

Vous pouvez transmettre un ensemble de valeurs de paramètres différentes à chaque fois que vous exécutez un modèle de flux de travail paramétré. Vous devez fournir une valeur pour chaque paramètre défini dans le modèle.

Commande gcloud

Vous pouvez transmettre un mappage de noms de paramètres et de valeurs à la commande gcloud dataproc workflow-templates instantiate avec l'option --parameters. Toutes les valeurs de paramètre définies dans le modèle doivent être fournies. Les valeurs fournies remplaceront les valeurs spécifiées dans le modèle.

Exemple de modèle de cluster géré paramétré

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

Exemple de modèle de sélecteur de cluster paramétré

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

API REST

Vous pouvez transmettre une carte parameters du paramètre names à values à l'API Dataproc workflowTemplates.instantiate. Toutes les valeurs de paramètre définies dans le modèle doivent être fournies. Les valeurs fournies remplaceront les valeurs spécifiées dans le modèle.

Exemple :

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