Actions d'initialisation

Lors de la création d'un cluster Cloud Dataproc, vous pouvez spécifier des actions d'initialisation dans des exécutables ou des scripts que Cloud Dataproc exécutera sur tous les nœuds du cluster Cloud Dataproc immédiatement après la configuration du cluster. Les actions d'initialisation vous permettent souvent de configurer les dépendances de tâches, telles que l'installation de packages Python. Vous pouvez ainsi soumettre les tâches au cluster sans avoir à installer de dépendances lors de leur exécution.

Vous trouverez des exemples de scripts d'actions d'initialisation fréquemment utilisés et d'autres exemples aux emplacements suivants :

Consignes et remarques importantes

  • Ne créez pas de clusters de production référençant des actions d'initialisation situées dans les buckets publics gs://goog-dataproc-initialization-actions-<REGION>. Ces scripts sont fournis en tant que mises en œuvre de référence et sont synchronisés avec les modifications apportées en continu au dépôt GitHub. Une nouvelle version d'une action d'initialisation dans des buckets publics risque de compromettre la création du cluster. À la place, copiez l'action d'initialisation des buckets publics dans votre bucket, comme illustré dans l'exemple suivant :
        REGION=<region>
        gsutil cp gs://goog-dataproc-initialization-actions-${REGION}/presto/presto.sh gs://my-bucket/
        
    Créez ensuite le cluster en référençant la copie :
        gcloud dataproc clusters create cluster-name 
        --initialization-actions gs://my-bucket/presto.sh
        ... other flags ...
    Vous pouvez décider quand synchroniser la copie de l'action d'initialisation avec les modifications de cette action qui sont apportées dans le bucket public ou dans le dépôt GitHub.
  • Les actions d'initialisation sont exécutées sur chaque nœud lors de la création du cluster. Elles sont également exécutées sur chaque nœud nouvellement ajouté lors du scaling ou de l'autoscaling des clusters pour augmenter leur capacité.
  • Les actions d'initialisation sont exécutées en tant qu'utilisateur root. Cela signifie que vous n'avez pas besoin d'utiliser la commande sudo.
  • Vous devez utiliser des chemins absolus dans les actions d'initialisation.
  • Les actions d'initialisation doivent utiliser une ligne shebang pour indiquer comment le script doit être interprété (par exemple, #!/bin/bash ou #!/usr/bin/python).
  • Si une action d'initialisation se termine par un code de sortie différent de zéro, l'opération de création de cluster indique un état "ERREUR". Pour déboguer l'action d'initialisation, connectez-vous via SSH aux instances de VM du cluster et examinez les journaux. Après avoir résolu le problème de l'action d'initialisation, vous pouvez supprimer le cluster, puis le recréer.
  • Si vous créez un cluster Dataproc avec des adresses IP internes uniquement, les tentatives d'accès à Internet lors d'une action d'initialisation échoueront à moins que vous n'ayez configuré des routes pour diriger le trafic via une passerelle NAT ou une passerelle VPN. Sans accès à Internet, vous pouvez activer l'accès privé à Google et placer des dépendances de tâches dans Cloud Storage. Les nœuds de cluster peuvent télécharger les dépendances depuis Cloud Storage à partir d'adresses IP internes.
  • Vous pouvez configurer des dépendances de tâches à l'aide d'images personnalisées Dataproc plutôt qu'avec des actions d'initialisation.

Utiliser les actions d'initialisation

Les actions d'initialisation de cluster peuvent être spécifiées quelle que soit la manière dont vous créez un cluster :

  • Via Google Cloud Console
  • Sur la ligne de commande à l'aide de l'outil de ligne de commande gcloud
  • De façon automatisée à l'aide de l'API clusters.create de Cloud Dataproc (consultez la section sur le paramètre NodeInitializationAction)

Commande gcloud

Lorsque vous créez un cluster à l'aide de la commande gcloud dataproc clusters create, spécifiez un ou plusieurs emplacements Cloud Storage (URI) des scripts ou exécutables d'initialisation avec l'option --initialization-actions, en les séparant par une virgule. Remarque : L'utilisation de plusieurs caractères "/" consécutifs dans un URI d'emplacement Cloud Storage après le préfixe "gs://" initial, par exemple "gs://bucket/my//object//name", n'est pas acceptée.

La syntaxe associée à cette option est illustrée ci-dessous. Vous pouvez l'afficher à partir de la ligne de commande en exécutant gcloud dataproc clusters create --help.

    gcloud dataproc clusters create cluster-name \
        --initialization-actions Cloud Storage URI(s) (gs://bucket/...) \
        --initialization-action-timeout timeout-value (default=10m) \
        ... other flags ...
    

Vous pouvez vous servir de l'option facultative --initialization-action-timeout afin de spécifier un délai avant expiration pour l'action d'initialisation. La valeur par défaut du délai avant expiration est de 10 minutes. Si l'exécutable ou le script d'initialisation n'est pas terminé à la fin du délai spécifié, Cloud Dataproc annule l'action d'initialisation.

API REST

Spécifiez un ou plusieurs scripts ou exécutables NodeInitializationAction dans le tableau ClusterConfig.initializationActions dans le cadre d'une requête API clusters.create.

Exemple

    POST /v1/projects/my-project-id/regions/us-central1/clusters/
    {
      "projectId": "my-project-id",
      "clusterName": "example-cluster",
      "config": {
        "configBucket": "",
        "gceClusterConfig": {
          "subnetworkUri": "default",
          "zoneUri": "us-central1-b"
        },
        "masterConfig": {
          "numInstances": 1,
          "machineTypeUri": "n1-standard-4",
          "diskConfig": {
            "bootDiskSizeGb": 500,
            "numLocalSsds": 0
          }
        },
        "workerConfig": {
          "numInstances": 2,
          "machineTypeUri": "n1-standard-4",
          "diskConfig": {
            "bootDiskSizeGb": 500,
            "numLocalSsds": 0
          }
        },
        "initializationActions": [
          {
            "executableFile": "gs://cloud-example-bucket/my-init-action.sh"
          }
        ]
      }
    }
    

Console

Lorsque vous créez un cluster avec Cloud Console, vous pouvez spécifier une ou plusieurs actions d'initialisation dans le champ Initialization actions. Pour afficher ce champ, développez le panneau Advanced options (Options avancées).
Entrez le ou les emplacements Cloud Storage associés à chaque action d'initialisation dans ce formulaire. Cliquez sur Browse (Parcourir) pour ouvrir la page "Navigateur Cloud Storage" dans Cloud Console et sélectionner un fichier d'initialisation. Chaque fichier d'initialisation doit être saisi séparément (appuyez sur <Entrée> pour ajouter une nouvelle entrée).

Transmettre des arguments aux actions d'initialisation

Dataproc définit des valeurs de métadonnées spéciales pour les instances exécutées dans vos clusters. Vous pouvez définir vos propres métadonnées personnalisées pour transmettre des arguments aux actions d'initialisation.

    gcloud dataproc clusters create cluster-name \
        --initialization-actions Cloud Storage URI(s) (gs://bucket/...) \
        --metadata name1=value1,name2=value2... \
        ... other flags ...
    

Les valeurs de métadonnées peuvent être lues dans les actions d'initialisation comme suit :

    var1=$(/usr/share/google/get_metadata_value attributes/name1)
    

Sélection de nœud

Si vous souhaitez limiter les actions d'initialisation au nœud maître ou aux nœuds de calcul, vous pouvez ajouter une logique simple de sélection de nœud à l'exécutable ou au script.

    ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
    if [[ "${ROLE}" == 'Master' ]]; then
      ... master specific actions ...
    else
      ... worker specific actions ...
    fi
    

Binaires de préproduction

Un scénario d'initialisation de cluster courant consiste en la préproduction de binaires de tâches sur un cluster afin d'éliminer le besoin de préparer ces binaires chaque fois qu'une tâche est soumise. Par exemple, supposons que le script d'initialisation suivant soit stocké dans gs://my-bucket/download-job-jar.sh, un emplacement de bucket Cloud Storage :

    #!/bin/bash
    ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
    if [[ "${ROLE}" == 'Master' ]]; then
      gsutil cp gs://my-bucket/jobs/sessionalize-logs-1.0.jar home/username
    fi
    

L'emplacement de ce script peut être transmis à la commande gcloud dataproc clusters create :

    gcloud dataproc clusters create my-dataproc-cluster \
        --initialization-actions gs://my-bucket/download-job-jar.sh
    

Cloud Dataproc exécute ce script sur tous les nœuds et, en conséquence de la logique de sélection de nœud du script, il télécharge le fichier jar sur le nœud maître. Les tâches soumises peuvent ensuite utiliser le fichier jar de préproduction :

    gcloud dataproc jobs submit hadoop \
        --cluster my-dataproc-cluster \
        --jar file:///home/username/sessionalize-logs-1.0.jar
    

Exemples d'actions d'initialisation

Vous trouverez des exemples de scripts d'actions d'initialisation fréquemment utilisés et d'autres scripts dans gs://goog-dataproc-initialization-actions-<REGION>, un bucket public Cloud Storage régional, et dans un dépôt GitHub. Pour contribuer à un script, consultez le document CONTRIBUTING.md, puis déposez une demande d'extraction.

Logging

Le résultat de l'exécution de chaque action d'initialisation est enregistré pour chaque instance dans /var/log/dataproc-initialization-script-X.log, où X correspond à l'index basé sur zéro de chaque script d'action d'initialisation successif. Par exemple, si votre cluster comporte deux actions d'initialisation, les résultats sont enregistrés dans /var/log/dataproc-initialization-script-0.log et /var/log/dataproc-initialization-script-1.log.

Étape suivante

Découvrez ces actions d'initialisation :