Initialisierungsaktionen

Beim Erstellen eines Dataproc-Clusters können Sie Initialisierungsaktionen in ausführbaren Dateien oder Skripts angeben, die von Dataproc auf allen Knoten im Dataproc-Cluster ausgeführt werden, unmittelbar nachdem der Cluster eingerichtet wurde. Initialisierungsaktionen richten häufig Jobabhängigkeiten ein, beispielsweise die Installation von Python-Paketen, sodass Jobs an den Cluster gesendet werden können, ohne Abhängigkeiten bei der Ausführung der Jobs zu installieren.

Beispiele für Skripts für Initialisierungsaktionen finden Sie an folgenden Stellen: Hinweis: Google unterstützt diese Beispiele nicht.

• GitHub-Repository
• Cloud Storage – in den regionalen öffentlichen gs://goog-dataproc-initialization-actions-REGION-Buckets

Wichtige Hinweise und Richtlinien

• Erstellen Sie keine Produktionscluster, die auf Initialisierungsaktionen in den öffentlichen gs://goog-dataproc-initialization-actions-REGION-Buckets verweisen. Diese Scripts dienen als Referenzimplementierungen. Sie werden mit laufenden Änderungen am GitHub-Repository synchronisiert. Aktualisierungen dieser Scripts können die Erstellung des Clusters beeinträchtigen. Kopieren Sie stattdessen die Initialisierungsaktion aus dem öffentlichen Bucket in einen versionierten Cloud Storage-Bucket-Ordner, wie im folgenden Beispiel gezeigt:

  REGION=COMPUTE_REGION
  gcloud storage cp gs://goog-dataproc-initialization-actions-${REGION}/cloud-sql-proxy/cloud-sql-proxy.sh \
      gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh
  

  Erstellen Sie dann den Cluster, indem Sie auf die Kopie in Cloud Storage verweisen:

  gcloud dataproc clusters create CLUSTER_NAME \
      --region=${REGION} \
      --initialization-actions=gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh \
      ...other flags...
  

• Initialisierungsaktionen werden während der Clustererstellung nacheinander auf jedem Knoten ausgeführt. Sie werden auch auf jedem hinzugefügten Knoten ausgeführt, wenn Cluster skaliert oder automatisch skaliert werden.

• Wenn Sie Initialisierungsaktionen aktualisieren, z. B. wenn Sie Ihre Cloud Storage-Initialisierungsaktionen mit Änderungen an Initialisierungsaktionen für öffentliche Buckets oder GitHub-Repositories synchronisieren, erstellen Sie einen neuen Ordner (vorzugsweise mit Versionsnamen), in dem die aktualisierten Initialisierungsaktionen abgelegt werden. Wenn Sie stattdessen die Initialisierungsaktion vor Ort aktualisieren, wird auf neuen Knoten, z. B. solchen, die vom Autoscaler hinzugefügt wurden, die aktualisierte Initialisierungsaktion ausgeführt, nicht die Initialisierungsaktion der vorherigen Version, die auf vorhandenen Knoten ausgeführt wurde. Solche Unterschiede bei der Initialisierungsaktion können zu inkonsistenten oder fehlerhaften Clusterknoten führen.

• Initialisierungsaktionen werden als root-Nutzer ausgeführt. Sie müssen sudo nicht verwenden.

• Verwenden Sie in Initialisierungsaktionen absolute Pfade.

• Verwenden Sie in den Initialisierungsaktionen eine Shebang-Zeile, um anzugeben, wie das Script interpretiert werden soll (z. B. #!/bin/bash oder #!/usr/bin/python).

• Wenn eine Initialisierungsaktion mit einem Exit-Code ungleich null beendet wird, meldet der Vorgang der Clustererstellung den Status "ERROR" (Fehler). Zur Fehlerbehebung der Initialisierungsaktion stellen Sie eine SSH-Verbindung zu den VM-Instanzen des Clusters her und überprüfen die Logs. Nachdem Sie das Problem mit der Initialisierungsaktion behoben haben, können Sie den Cluster löschen und anschließend neu erstellen.

• Wenn Sie einen Dataproc-Cluster mit nur mit internen IP-Adressen erstellen, schlagen Versuche, bei einer Initialisierungsaktion auf github.com zuzugreifen, fehl. Dies ist nicht der Fall, wenn Sie Routen zur Weiterleitung des Traffics über Cloud NAT oder ein Cloud VPN konfiguriert haben. Ohne Zugriff auf das Internet können Sie den privaten Google-Zugriff aktivieren und Jobabhängigkeiten in Cloud Storage platzieren. Clusterknoten können die Abhängigkeiten von Cloud Storage über interne IP-Adressen herunterladen.

• Sie können benutzerdefinierte Dataproc-Images anstelle von Initialisierungsaktionen verwenden, um Jobabhängigkeiten einzurichten.

• Initialisierungsverarbeitung:

  • Image-Cluster vor Version 2.0:
    • Master: Damit Initialisierungsaktionen auf Mastern ausgeführt werden können, um Dateien in HDFS zu schreiben, werden Initialisierungsaktionen für Masterknoten erst gestartet, wenn HDFS beschreibbar ist (sobald HDFS den abgesicherten Modus verlassen hat und mindestens zwei HDFS-Datenknoten verknüpft wurden).
    • Worker: Wenn Sie das Clusterattribut dataproc:dataproc.worker.custom.init.actions.mode auf RUN_BEFORE_SERVICES festlegen, führt jeder Worker seine Initialisierungsaktionen aus, bevor er seinen HDFS-Datenknoten und die YARN-Knotenmanager-Daemons startet. Da Dataproc Master-Initialisierungsaktionen erst ausführt, wenn HDFS beschreibbar ist, sodass zwei HDFS-Datenknoten-Daemons aktiv sein müssen, kann das Festlegen dieses Attributs die Clustererstellungszeit erhöhen.

  • Image-Cluster ab Version 2.0:

    • Master: Master-Initialisierungsaktionen können ausgeführt werden, bevor HDFS beschreibbar ist. Wenn Sie Initialisierungsaktionen ausführen, die Dateien in HDFS bereitstellen oder von der Verfügbarkeit von HDFS-abhängigen Diensten wie Ranger abhängen, können Sie Folgendes festlegen: dataproc.master.custom.init.actions.mode Clusterattribut in RUN_AFTER_SERVICES. Hinweis: Da diese Attributeinstellung die Zeit zur Erstellung des Clusters erhöhen kann (siehe Erläuterung der Verzögerung bei der Clustererstellung für Image-Worker vor Version 2.0), verwenden Sie es nur, wenn erforderlich (im Allgemeinen sollten Sie auf die Standardeinstellung RUN_BEFORE_SERVICES für dieses Attribut zurückgreifen.)
    • Worker: Das Clusterattribut dataproc:dataproc.worker.custom.init.actions.mode ist auf RUN_BEFORE_SERVICES festgelegt und kann nicht an den Cluster übergeben werden, wenn der Cluster erstellt wird (die Attributeinstellung kann nicht geändert werden). Jeder Worker führt seine Initialisierungsaktionen aus, bevor er seinen HDFS-Datenknoten und die YARN-Knotenmanager-Daemons startet. Da Dataproc nicht wartet, bis HDFS beschreibbar ist, bevor Master-Initialisierungsaktionen ausgeführt werden, werden Master- und Worker-Initialisierungsaktionen parallel ausgeführt.

  • Empfehlungen

    • Ermitteln Sie über Metadaten die Rolle eines Knotens, um in Abhängigkeit Initialisierungsaktionen auf Knoten auszuführen. Weitere Informationen finden Sie unter Clustermetadaten verwenden.
    • Erstellen Sie aus Gründen der Stabilität eine Kopie einer Initialisierungsaktion in einem Cloud Storage-Bucket. Weitere Informationen zur Verwendung von Initialisierungsaktionen
    • Fügen Sie beim Herunterladen aus dem Internet Wiederholungsversuche hinzu, um die Initialisierungsaktion zu stabilisieren.

Initialisierungsaktionen verwenden

Cluster-Initialisierungsaktionen können unabhängig davon angegeben werden, mit welcher Methode der Cluster erstellt wird:

• Über die Google Cloud Console
• gcloud CLI verwenden
• Programmatisch mit der Dataproc API clusters.create (siehe NodeInitializationAction)

Befehl "gcloud"

Geben Sie beim Erstellen eines Clusters mit dem Befehl gcloud dataproc clusters create einen oder mehrere kommagetrennte Cloud Storage-Speicherorte (URIs) der ausführbaren Initialisierungsdateien oder Skripts mit dem Flag --initialization-actions an. Hinweis: Mehrere aufeinanderfolgende "/"s in einem Cloud Storage-Standort-URI nach dem ersten "gs://", z. B. "gs://bucket/my//object//name", werden nicht unterstützt. Führen Sie gcloud dataproc clusters create --help aus, um Informationen zum Befehl zu erhalten.

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

Hinweise:

• Verwenden Sie das Flag --initialization-action-timeout, um ein Zeitlimit für die Initialisierungsaktion anzugeben. Das standardmäßige Zeitlimit beträgt 10 Minuten. Wenn die ausführbare Datei oder das Skript der Initialisierung bei Ablauf der Zeitüberschreitung noch nicht abgeschlossen ist, wird die Initialisierungsaktion abgebrochen.
• Führen Sie mit dem Clusterattribut dataproc:dataproc.worker.custom.init.actions.mode die Initialisierungsaktion auf primären Workern aus, bevor Sie den Knotenmanager und die Datenknoten-Daemons starten.

Anfrage zur Clustererstellung über die Google Cloud Console Klicken Sie links unten auf der Dataproc-Seite Cluster erstellen auf die Links Entsprechende REST-Anfrage oder Befehlszeile, damit die Google Cloud Console eine entsprechende API REST-Anfrage oder einen Befehl des gcloud-Tools erstellt.

executionTimeout--initialization-action-timeout

REST API

Geben Sie ein oder mehrere Skripts oder ausführbare Dateien in einem ClusterConfig.initializationActions-Array als Teil der API-Anfrage clusters.create an.

Beispiel

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

Anfrage zur Clustererstellung über die Google Cloud Console stellen: Klicken Sie in der Cloud Console unten links auf der Dataproc-Seite Cluster erstellen auf den Link für die entsprechende REST API oder Befehlszeile. Die Cloud Console erstellt dann eine entsprechende API REST-Anfrage oder einen Befehl des gcloud-Tools.

executionTimeout--initialization-action-timeout

Console

Öffnen Sie die Dataproc-Seite Cluster erstellen und wählen Sie dann das Fenster Cluster anpassen aus.

Geben Sie im Abschnitt „Initialisierungsaktionen“ die Speicherorte der Cloud Storage-Buckets jeder Initialisierungsaktion in die Felder Ausführbare Datei ein. Klicken Sie auf Durchsuchen, um die Seite „Cloud Storage-Browser“ in der Google Cloud Console zu öffnen und ein Script oder eine ausführbare Datei auszuwählen. Klicken Sie auf Initialisierungsaktion hinzufügen, um jede Datei hinzuzufügen.

Argumente an Initialisierungsaktionen übergeben

Dataproc legt spezielle Metadatenwerte für die Instanzen fest, die in Ihrem Cluster ausgeführt werden. Sie können Ihre eigenen benutzerdefinierten Metadaten festlegen, um Argumente an Initialisierungsaktionen zu übergeben.

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

Metadatenwerte können auf folgende Weise in Initialisierungsaktionen gelesen werden:

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

Knotenauswahl

Wenn Sie die Initialisierungsaktionen auf Master-, Treiber- oder Worker-Knoten beschränken möchten, können Sie der ausführbaren Datei oder dem Skript eine einfache Knotenauswahllogik hinzufügen.

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

Staging von Binärdateien

Ein gängiges Szenario der Cluster-Initialisierung ist das Staging von binären Jobdateien auf einem Cluster. Hierdurch wird vermieden, dass die Binärdateien bei jeder Jobausführung einem Staging-Prozess unterzogen werden. Nehmen Sie beispielsweise an, dass das folgende Initialisierungsskript unter gs://my-bucket/download-job-jar.sh (ein Speicherort für Cloud Storage-Bucket) gespeichert wird:

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

Der Speicherort dieses Skripts kann an den Befehl gcloud dataproc clusters create übergeben werden:

gcloud dataproc clusters create my-dataproc-cluster \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/download-job-jar.sh

Dataproc führt dieses Skript auf allen Knoten aus. Die JAR-Datei wird entsprechend der Knotenauswahllogik des Skripts auf den Master-Knoten heruntergeladen. Gesendete Jobs können dann die JAR-Datei in der Vor-Staging-Phase verwenden:

gcloud dataproc jobs submit hadoop \
    --cluster=my-dataproc-cluster \
    --region=${REGION} \
    --jar=file:///home/username/sessionalize-logs-1.0.jar

Beispiele für Initialisierungsaktionen

Häufig verwendete und sonstige Beispielinitialisierungsaktionen werden in einem regionalen öffentlichen Cloud Storage-Bucket (gs://goog-dataproc-initialization-actions-<REGION>) und in einem GitHub-Repository bereitgestellt. Wenn Sie ein Skript beitragen möchten, lesen Sie das Dokument CONTRIBUTING.md und senden Sie eine Pull-Anfrage.

Logging

Die Ausgabe der einzelnen Initialisierungsaktionen wird für jede Instanz im Log /var/log/dataproc-initialization-script-X.log erfasst, wobei X der nullbasierte Index jedes nachfolgenden Skripts mit Initialisierungsaktionen ist. Wenn Ihr Cluster beispielsweise zwei Initialisierungsaktionen hat, werden die Ausgaben in /var/log/dataproc-initialization-script-0.log und /var/log/dataproc-initialization-script-1.log protokolliert.

Nächste Schritte

GitHub-Initialisierungsaktionen entdecken.