Fehlerbehebung bei Flex-Vorlagen

Auf dieser Seite finden Sie Tipps und Strategien zur Fehlerbehebung, die nützlich sein könnten, wenn Sie flexible Dataflow-Vorlagen verwenden. Standardmäßig beträgt das Zeitlimit für den Startvorgang der flexiblen Vorlage 12 Minuten. Dieser Startvorgang umfasst das Abrufen des Vorlagen-Container-Images und das Ausführen des Codes zum Erstellen des Jobgraphen. Wenn der Start nicht innerhalb dieses 12-minütigen Zeitfensters abgeschlossen wird, schlägt der Job mit dem Fehler „Timeout in polling result file“ fehl. Anhand dieser Informationen können Sie ein Zeitlimit für die Abfrage ermitteln, den Grund für das Zeitlimit ermitteln und das Problem beheben.

Fehler beim Laden der Vorlagenliste in der Google Cloud Console

Wenn Sie in der Google Cloud Console versuchen, die Liste der Vorlagen auf der Dataflow-Seite Job aus Vorlage erstellen aufzurufen, wird ein Fehler wie der folgende angezeigt:

Error retrieving templates. Custom templates can still be used.

Wenn Ihre Organisation PAB-Richtlinien (Principal Access Boundary) verwendet, können Hauptkonten (z. B. Nutzer oder Dienstkonten) möglicherweise keine von Google bereitgestellten Vorlagen ansehen und ausführen. Versuchen Sie, dieses Problem mit der Anleitung unter Mit Principal Access Boundary-Richtlinien auf von Google bereitgestellte Vorlagen zugreifen zu beheben.

Fehler bei Zeitüberschreitungen bei Abfragen

Ihr Job gibt möglicherweise eine der folgenden Fehlermeldungen zurück:

Timeout in polling result file: FILE_PATH. Possible causes are:
1. Your launch takes too long time to finish. Please check the logs on stackdriver.
2. Service account SERVICE_ACCOUNT may not have enough permissions to pull
container image IMAGE_PATH or create new objects in FILE_PATH.
3. Transient errors occurred, please try again.

Timeout in polling result file: FILE_PATH.
Service account: SERVICE_ACCOUNT
Image URL: IMAGE_PATH
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

Dieser Fehler kann folgende Ursachen haben:

  1. Das Basis-Docker-Image wurde überschrieben.
  2. Das Dienstkonto, mit dem SERVICE_ACCOUNT gefüllt wird, hat nicht alle erforderlichen Berechtigungen.
  3. Externe IP-Adressen sind deaktiviert und VMs können keine Verbindung zu der Gruppe von externen IP-Adressen herstellen, die von Google APIs und Diensten verwendet werden.
  4. Die Launcher-VM kann gcr.io nicht auflösen oder darauf zugreifen.
  5. Großes Container-Image für flexible Vorlagen.
  6. Das Programm, das die Grafik erstellt, braucht zu lange.
  7. Der Code, der auf der Launcher-VM ausgeführt wird, braucht zu lange.
  8. Gelegentliche Netzwerk- oder Cloud Storage-Fehler.
  9. Pipelineoptionen werden überschrieben.
  10. Python-Nutzer: Das Installieren oder Staging von Abhängigkeiten dauert zu lange.
  11. Ein vorübergehender Fehler ist aufgetreten.

Prüfen Sie zur Behebung dieses Problems zuerst die Joblogs auf Fehler und versuchen Sie es noch einmal.

Folgen Sie der Anleitung im Abschnitt Probleme beim frühen Start, um das Logging für den seriellen Port zu aktivieren. Dadurch können zusätzliche Informationen angezeigt werden.

Wenn das Problem durch diese Schritte nicht behoben wird, führen Sie die folgenden Schritte zur Fehlerbehebung aus.

Optional: Vorlagen ausführen, um das Problem weiter zu diagnostizieren

Verwenden Sie die folgenden Strategien, um genauer zu ermitteln, welche der oben genannten Ursachen diesen Fehler verursacht:

  1. Führen Sie die von Google bereitgestellte Vorlage WordCount aus. Geben Sie Parameter an, die für Ihren Anwendungsfall eindeutig sind, z. B. das Subnetzwerk aus einem freigegebene VPC-Projekt, die private IP-Adresse für Worker-VMs und das Dataflow-Worker-Dienstkonto, das Sie verwenden möchten. Weitere Informationen zur Angabe dieser Parameter finden Sie in der gcloud-Referenz und der API-Referenz.

    Wenn Sie diesen Job erfolgreich abschließen können, sind Netzwerk, IAM-Berechtigungen und privater Google-Zugriff wahrscheinlich richtig konfiguriert.

  2. Führen Sie die Kurzanleitung Pipeline mit dem Job-Builder ausführen aus, bei der der Job als flexible Vorlage ausgeführt wird. Wenn Ihr Job fehlschlägt, bevor die Worker-VM gestartet wird, greifen Sie auf die Launcher-VM zu und versuchen Sie, ein Docker-Beispiel-Image mit einem Befehl wie dem folgenden herunterzuladen:

    docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-template

    Wenn dieser Befehl fehlschlägt, liegt möglicherweise ein Netzwerkproblem beim Herunterladen von Images vor. Wenden Sie sich in diesem Fall an Ihr internes Netzwerkteam.

  3. Führen Sie eine von Google bereitgestellte flexible Vorlage aus und prüfen Sie das Ergebnis. Wenn der von Google bereitgestellte Vorlagenjob erfolgreich abgeschlossen wird, liegt das Problem wahrscheinlich an Ihren benutzerdefinierten Vorlagencodedateien. In diesem Fall müssen Sie die Fehlerbehebung für Ihren spezifischen Code fortsetzen, um das Problem zu beheben.

Docker-Einstiegspunkt prüfen

Führen Sie diesen Schritt aus, wenn Sie eine Vorlage aus einem benutzerdefinierten Docker-Image ausführen, anstatt eine der bereitgestellten Vorlagen zu verwenden.

Suchen Sie mit dem folgenden Befehl nach dem Containereinstiegspunkt:

docker inspect $TEMPLATE_IMAGE

Die erwartete Ausgabe sieht so aus:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

Wenn Sie eine andere Ausgabe erhalten, wird der Einstiegspunkt Ihres Docker-Containers überschrieben. Stellen Sie $TEMPLATE_IMAGE wieder auf die Standardeinstellung her.

Dienstkontoberechtigungen prüfen

Prüfen Sie, ob das in der Nachricht erwähnte Dienstkonto die folgenden Berechtigungen hat:

  • Es muss den Cloud Storage-Pfad lesen und schreiben können, mit dem ${file_path} in der Nachricht gefüllt wird.
  • Es muss das Docker-Image lesen können, mit dem ${image_url} in der Nachricht gefüllt wird.

Privaten Google-Zugriff konfigurieren

Wenn externe IP-Adressen deaktiviert sind, müssen Sie Compute Engine-VMs erlauben, eine Verbindung zu der Gruppe von externen IP-Adressen herzustellen, die von Google APIs und Diensten verwendet werden. Aktivieren Sie den privaten Google-Zugriff in dem Subnetz, das von der Netzwerkschnittstelle der VM verwendet wird.

Weitere Konfigurationsdetails finden Sie unter Privaten Google-Zugriff konfigurieren.

Wenn einer Compute Engine-VM eine externe IP-Adresse fehlt, die der Netzwerkschnittstelle zugewiesen ist, kann sie standardmäßig nur Pakete an andere interne IP-Adressen senden.

GCR.io-Zugriffsprobleme

VMs zum Starten von flexiblen Vorlagen benötigen Zugriff auf gcr.io, um einen Logging-Agent-Container (gcr.io/dataflow-templates-base/template-launcher-logger-distroless) abzurufen. Dieser Agent ist für das Streamen von Launcher-Logs an Cloud Logging verantwortlich. Wenn die Launcher-VM gcr.io nicht auflösen oder keine Verbindung dazu herstellen kann, reagiert der Startvorgang möglicherweise nicht mehr, was zu einer Zeitüberschreitung bei der Abfrage führt.

Dieses Problem kann auch auftreten, wenn Ihr benutzerdefiniertes Vorlagen-Image in Artifact Registry gespeichert ist, da der Logging-Agent immer aus gcr.io abgerufen wird.

So diagnostizieren und beheben Sie dieses Problem:

  1. Logging für seriellen Port aktivieren: Folgen Sie der Anleitung im Abschnitt Probleme beim frühen Start. Wenn Sie feststellen, dass der cloud-init-Prozess hängen bleibt oder Fehler im Zusammenhang mit gcr-wait-online.service auftreten, liegt wahrscheinlich ein DNS- oder Netzwerkproblem vor.

  2. SSH-Verbindung zur Launcher-VM herstellen: Verwenden Sie den Befehl gcloud compute ssh, um eine Verbindung zur Launcher-VM herzustellen, während sie noch ausgeführt wird:

    gcloud compute ssh launcher-JOB_ID --tunnel-through-iap

    Ersetzen Sie JOB_ID durch die ID Ihres Dataflow-Jobs.

  3. DNS-Auflösung prüfen: Führen Sie die folgenden Befehle auf der Launcher-VM aus:

    curl -I https://gcr.io

    Wenn der Befehl mit dem Fehler "Could not resolve host" fehlschlägt, fehlt in Ihrer DNS-Konfiguration ein Eintrag für gcr.io.

  4. Nach hängengebliebenen Startdiensten suchen: Prüfen Sie das Ausgabeprotokoll cloud-init:

    sudo cat /var/log/cloud-init-output.log

    Suchen Sie nach Nachrichten, die darauf hinweisen, dass der Prozess auf das Netzwerk oder auf die Verfügbarkeit von gcr.io wartet.

Achten Sie außerdem darauf, dass die DNS-Einstellungen Ihrer VPC die Auflösung von gcr.io zulassen. In einigen privaten Netzwerkkonfigurationen müssen Sie möglicherweise einen bestimmten DNS-A-Eintrag für gcr.io hinzufügen, der auf die IP-Bereiche der eingeschränkten Google APIs oder privaten Google APIs verweist.

Großes Container-Image

Wenn Ihr Container-Image für die flexible Vorlage groß ist, kann das Abrufen und Starten der Vorlage das Standardzeitlimit von 12 Minuten überschreiten, was zu einem Jobfehler führt.

Versuchen Sie Folgendes, um das Problem zu beheben:

  • Optimieren Sie Ihr Image, um die Größe zu reduzieren und den Pull-Vorgang zu beschleunigen.
  • Verwenden Sie das Flag --launcher-machine-type, um einen Maschinentyp mit mehr CPU-Kernen auszuwählen. Dadurch wird das Image schneller abgerufen und der Start beschleunigt.
  • Sie können das Zeitlimit für den Start über das standardmäßige Limit von 12 Minuten (720 Sekunden) hinaus verlängern. Verwenden Sie dazu das Flag --launcher-vm-timeout-secs in der gcloud CLI oder die Startoption ft_launch_timeout_secs in der REST API und im Managed Service for Apache Airflow. Beispiele finden Sie unter Zeitlimit für den Start der flexiblen Vorlage verlängern.

Prüfen, ob das Launcher-Programm nicht beendet werden kann

Das Programm, das die Pipeline erstellt, muss abgeschlossen sein, bevor die Pipeline gestartet werden kann. Der Abfragefehler könnte darauf hinweisen, dass es zu lange gedauert hat.

Sie können die Ursache im Code beispielsweise so ermitteln:

  • Achten Sie darauf, dass das Beenden des Programms nicht von Threads blockiert wird. Einige Clients erstellen möglicherweise ihre eigenen Threads. Wenn diese Clients nicht heruntergefahren werden, wartet das Programm für immer, bis diese Threads verbunden werden.
  • Verwenden Sie im Code, der Ihre Pipeline definiert, nicht waitUntilFinish (für Java) oder wait_until_finish (für Python). Diese Funktionen verhindern, dass das Programm beendet wird, wodurch die flexible Vorlage die Pipeline nicht starten kann.

Pipelines, die direkt gestartet werden und keine Vorlage verwenden, haben diese Einschränkungen nicht. Wenn die Pipeline also direkt (nicht als Vorlage) funktionierte, könnte die Verwendung einer Vorlage die Ursache sein. Wenn Sie das Problem in der Vorlage finden und die Vorlage beheben, kann das Problem möglicherweise behoben werden.

Lang andauernder Code in der Launcher-VM

Wenn die Ausführung des Codes in Ihrem Hauptprogramm zu lange dauert, kann es zu einer Zeitüberschreitung der flexiblen Vorlage kommen, bevor die Pipeline gestartet wird. Das kann passieren, wenn der Code während der Initialisierung komplexe Berechnungen durchführt oder synchrone Aufrufe an externe Ressourcen sendet.

Um dieses Problem zu diagnostizieren, prüfen Sie die Joblogs auf Vorgänge, die lange dauern. Beispiele hierfür sind Anfragen für externe Ressourcen, große Datensuchen oder komplexe Initialisierungslogik, die Sie in die Pipeline-Ausführungsphase verschieben können. Wenn Ihre Pipeline nach der Optimierung der Initialisierung immer noch mehr als 12 Minuten zum Starten benötigt, lesen Sie den Abschnitt Zeitüberschreitung beim Start der flexiblen Vorlage verlängern.

Gelegentliche Netzwerk- oder Cloud Storage-Fehler

Aufgrund einer hohen Netzwerklatenz oder vorübergehender Probleme mit der Cloud Storage API können gelegentlich die Fehler „Timeout in polling result file“ oder „Failed to read the result file“ auftreten. Chronische Netzwerküberlastung in Ihrer VPC, insbesondere im Pfad für den privater Google-Zugriff, führt häufig zu Latenzen von 400–500 ms.

Ein „Timeout in polling result file“ ist in der Regel ein langsamer Fehler, während ein „Failed to read the result file“ ein schneller Fehler ist. Beide weisen jedoch oft auf dasselbe zugrunde liegende Verbindungsproblem hin.

So diagnostizieren Sie diese zeitweiligen Fehler:

  1. Netzwerklatenz prüfen: Überwachen Sie die Netzwerklatenz in Ihrer VPC. Eine anhaltend hohe Latenz kann zu Zeitüberschreitungen führen, wenn die Launcher-VM versucht, die Job-Ergebnisdatei in Cloud Storage zu schreiben oder daraus zu lesen.

  2. Cloud Storage API-Messwerte überwachen:

    1. Rufen Sie in der Google Cloud Console das Dashboard APIs und Dienste auf.

      Zu „Aktivierte APIs und Dienste“

    2. Filtern Sie nach der Cloud Storage API und wählen Sie sie aus.

    3. Sehen Sie sich die Diagramme für Traffic (gesendete und empfangene Byte) und Fehlerrate an.

    4. Suchen Sie nach Spitzen bei 5xx-Fehlern (z. B. 503-Fehlern), die genau mit dem Zeitpunkt der Jobfehler übereinstimmen.

Wenn Sie Spitzen bei Fehlern oder eine hohe Latenz feststellen, untersuchen Sie die Netzwerkleistung Ihrer VPC oder wenden Sie sich an Cloud Customer Care, um Unterstützung bei potenziellen Dienstunterbrechungen zu erhalten.

Prüfen, ob erforderliche Pipelineoptionen unterdrückt werden

Bei Verwendung von flexiblen Vorlagen haben Sie die Möglichkeit, einige, aber nicht alle Pipelineoptionen bei der Pipelineinitialisierung zu konfigurieren. Weitere Informationen finden Sie im Abschnitt Jobdatei konnte nicht gelesen werden in diesem Dokument.

Python-Nutzer: Abhängigkeitsverwaltung

Wenn Sie einen Python-Flex-Vorlagenjob ausführen, der zusätzliche Abhängigkeiten in einer requirements.txt-Datei bereitstellt, kann der Job möglicherweise nicht gestartet werden. Dieser Fehler tritt auf, wenn das Herunterladen oder Installieren der in der Anforderungsdatei angegebenen Abhängigkeiten länger dauert als die für das Starten der Flexible Vorlage vorgesehene Zeit.

Optimieren Sie die Leistung Ihres Jobs, indem Sie die Abhängigkeiten beim Erstellen der Vorlage vorab verpacken, damit sie beim Starten der Vorlage nicht heruntergeladen oder installiert werden müssen. Weitere Informationen finden Sie im Abschnitt Paketabhängigkeiten für Python unter „Flexible Vorlagen konfigurieren“. Wenn das Staging von Abhängigkeiten oder das Erstellen des Ausführungsgraphen immer noch das standardmäßige Zeitlimit von 12 Minuten für den Start überschreitet, lesen Sie den Abschnitt Zeitlimit für den Start der flexiblen Vorlage verlängern.

Zeitlimit für den Start der flexiblen Vorlage verlängern

Standardmäßig erzwingt Dataflow ein Zeitlimit von 720 Sekunden (12 Minuten) für die Startphase der flexiblen Vorlage. Wenn das Abrufen großer Container-Images, das Bereitstellen von Abhängigkeiten oder das Erstellen komplexer Ausführungsgraphen länger als 720 Sekunden dauert, können Sie dieses Zeitlimit erhöhen, indem Sie die Option für das Startzeitlimit für Ihre Startmethode konfigurieren.

gcloud-CLI

Wenn Sie das Zeitlimit für die Launcher-VM verlängern möchten, wenn Sie eine flexible Vorlage über die gcloud CLI ausführen, übergeben Sie das Flag --launcher-vm-timeout-secs an den Befehl gcloud dataflow flex-template run:

gcloud dataflow flex-template run JOB_NAME \
  --template-file-gcs-location=TEMPLATE_GCS_PATH \
  --region=REGION \
  --launcher-vm-timeout-secs=TIMEOUT_SECONDS

Ersetzen Sie die folgenden Werte:

  • JOB_NAME: der Name Ihres Dataflow-Jobs.
  • TEMPLATE_GCS_PATH: Der Cloud Storage-URI Ihrer Spezifikationsdatei für die flexible Vorlage, z. B. gs://my-bucket/templates/my-template.json.
  • REGION: die Dataflow-Region, in der der Job ausgeführt wird.
  • TIMEOUT_SECONDS: die Zeitüberschreitung der Launcher-VM in Sekunden. Geben Sie eine positive Ganzzahl ohne Einheitssuffix an. Das Standardzeitlimit beträgt 720, also 12 Minuten. Wenn Sie das Zeitlimit verlängern möchten, geben Sie eine Ganzzahl größer als 720 und bis zu 5400 (90 Minuten) an, z. B. 1200 für 20 Minuten oder 1800 für 30 Minuten.

REST API

Wenn Sie eine flexible Vorlage durch Aufrufen des REST-Endpunkts projects.locations.flexTemplates.launch starten, legen Sie den Schlüssel ft_launch_timeout_secs in der Zuordnung launchParameter.launchOptions auf einen String fest, der die Zeitüberschreitungsdauer in Sekunden als Ganzzahl ohne Einheitssuffix enthält:

{
  "launchParameter": {
    "jobName": "JOB_NAME",
    "containerSpecGcsPath": "TEMPLATE_GCS_PATH",
    "launchOptions": {
      "ft_launch_timeout_secs": "TIMEOUT_SECONDS"
    }
  }
}

Ersetzen Sie die folgenden Werte:

  • JOB_NAME: der Name Ihres Dataflow-Jobs.
  • TEMPLATE_GCS_PATH: Der Cloud Storage-URI Ihrer Spezifikationsdatei für die flexible Vorlage, z. B. gs://my-bucket/templates/my-template.json.
  • TIMEOUT_SECONDS: die Zeitüberschreitung der Launcher-VM in Sekunden. Geben Sie eine positive Ganzzahl als String ohne Einheitssuffix an. Das Standardzeitlimit ist "720", also 12 Minuten. Wenn Sie das Zeitlimit verlängern möchten, geben Sie eine Ganzzahl größer als 720 und bis zu 5400 (90 Minuten) an, z. B. "1200" für 20 Minuten oder "1800" für 30 Minuten.

Managed Airflow

Wenn Sie Flexible Vorlagenjobs in Managed Airflow oder Apache Airflow mit dem Operator DataflowStartFlexTemplateOperator orchestrieren, fügen Sie den Schlüssel ft_launch_timeout_secs unter launchParameter.launchOptions im Wörterbuch body ein:

from airflow.providers.google.cloud.operators.dataflow import (
    DataflowStartFlexTemplateOperator,
)

start_flex_template = DataflowStartFlexTemplateOperator(
    task_id="start_flex_template",
    project_id="PROJECT_ID",
    location="REGION",
    body={
        "launchParameter": {
            "jobName": "JOB_NAME",
            "containerSpecGcsPath": "TEMPLATE_GCS_PATH",
            "launchOptions": {
                "ft_launch_timeout_secs": "TIMEOUT_SECONDS",
            },
        }
    },
)

Ersetzen Sie die folgenden Werte:

  • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
  • REGION: die Dataflow-Region, in der der Job ausgeführt wird.
  • JOB_NAME: der Name Ihres Dataflow-Jobs.
  • TEMPLATE_GCS_PATH: Der Cloud Storage-URI Ihrer Spezifikationsdatei für die flexible Vorlage, z. B. gs://my-bucket/templates/my-template.json.
  • TIMEOUT_SECONDS: die Zeitüberschreitung der Launcher-VM in Sekunden. Geben Sie eine positive Ganzzahl als String ohne Einheitssuffix an. Das Standardzeitlimit ist "720", also 12 Minuten. Wenn Sie das Zeitlimit verlängern möchten, geben Sie eine Ganzzahl größer als 720 und bis zu 5400 (90 Minuten) an, z. B. "1200" für 20 Minuten oder "1800" für 30 Minuten.

Fehler beim Starten von Jobs

Der folgende Abschnitt enthält häufige Fehler beim Starten von Jobs sowie Schritte zur Behebung dieser Fehler.

Berechtigung beim Laden einer Vorlagendatei verweigert

Wenn Sie versuchen, eine von Google bereitgestellte Vorlage mit der gcloud CLI auszuführen, wird ein Fehler wie der folgende angezeigt:

ERROR: (gcloud.dataflow.flex-template.run) PERMISSION_DENIED: Template file
failed to load: TEMPLATE_PATH. Permissions denied.
USER does not have storage.objects.get access to the Google
Cloud Storage object. Operations on resource are denied due to an IAM
Principal Access Boundary Policy.

TEMPLATE_PATH ist ein Pfad zu einer Vorlage in einem Cloud Storage-Bucket, der die von Google bereitgestellten Vorlagen enthält, z. B. gs://dataflow-templates oder gs://dataflow-templates-REGION_NAME.

Wenn Ihre Organisation PAB-Richtlinien (Principal Access Boundary) verwendet, können Hauptkonten (z. B. Nutzer oder Dienstkonten) möglicherweise keine von Google bereitgestellten Vorlagen ansehen und ausführen. Versuchen Sie, dieses Problem mit der Anleitung unter Mit Principal Access Boundary-Richtlinien auf von Google bereitgestellte Vorlagen zugreifen zu beheben.

Probleme beim frühen Start

Wenn der Start der Vorlage in einem frühen Stadium fehlschlägt, sind möglicherweise keine regulären Flex-Vorlagenlogs verfügbar. Zum Untersuchen von Startproblemen aktivieren Sie das Logging für den seriellen Port für die Vorlagen-Launcher-VM.

Legen Sie für die Option enableLauncherVmSerialPortLogging den Wert true fest, um das Logging für Java-Vorlagen zu aktivieren. Zum Aktivieren des Loggings für Python- und Go-Vorlagen legen Sie für die Option enable_launcher_vm_serial_port_logging den Wert true fest. In der Google Cloud Console wird der Parameter unter Optionale Parameter als Logging des seriellen Ports für die Launcher-VM aktivieren aufgeführt.

Sie können die Logs für die Ausgabe des seriellen Ports der Vorlagen-Launcher-VM in Cloud Logging ansehen. Verwenden Sie die Abfrage resource.type="gce_instance" "launcher-number", um die Logs für eine bestimmte Launcher-VM zu ermitteln. Dabei beginnt number mit dem aktuellen Datum im Format YYYMMDD.

Ihre Organisationsrichtlinie lässt das Logging der Ausgabe des seriellen Ports möglicherweise nicht zu.

Jobdatei konnte nicht gelesen werden

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, schlägt der Job möglicherweise mit dem folgenden Fehler fehl:

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...

Dieser Fehler tritt auf, wenn die erforderlichen Pipeline-Initialisierungsoptionen überschrieben werden. Bei Verwendung von flexiblen Vorlagen können Sie einige, aber nicht alle Pipelineoptionen bei der Pipelineinitialisierung konfigurieren. Wenn die von der flexiblen Vorlage erforderlichen Befehlszeilenargumente überschrieben werden, kann es sein, dass der Job die vom Vorlagen-Launcher übergebenen Pipelineoptionen ignoriert, überschreibt oder verwirft. Der Job wird möglicherweise nicht gestartet, oder es wird ein Job gestartet, der die flexible Vorlage nicht verwendet.

Ändern Sie zur Vermeidung dieses Problems während der Pipelineinitialisierung die folgenden Pipelineoptionen im Nutzercode oder in der metadata.json-Datei nicht:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

Ergebnisdatei konnte nicht gelesen werden

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, schlägt der Job möglicherweise mit dem folgenden Fehler fehl:

Failed to read the result file : gs://BUCKET_NAME...

Dieser Fehler tritt auf, wenn das Compute Engine-Standarddienstkonto nicht alle Berechtigungen hat, die zum Ausführen einer flexiblen Vorlage erforderlich sind.

Eine Liste der erforderlichen Berechtigungen finden Sie unter Berechtigungen zum Ausführen einer flexiblen Vorlage.

Dieser Fehler kann auch folgende Ursachen haben:

Berechtigung für Ressource verweigert

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, schlägt der Job möglicherweise mit dem folgenden Fehler fehl:

Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).

Dieser Fehler tritt auf, wenn das verwendete Dienstkonto nicht berechtigt ist, auf erforderliche Ressourcen zum Ausführen einer flexiblen Vorlage zuzugreifen.

Prüfen Sie, ob das Dienstkonto die erforderlichen Berechtigungen hat, um dieses Problem zu vermeiden. Passen Sie die Dienstkontoberechtigungen nach Bedarf an.

Flag angegeben, aber nicht definiert

Wenn Sie versuchen, eine flexible Go-Vorlage mit der Pipelineoption worker_machine_type auszuführen, schlägt die Pipeline mit dem folgenden Fehler fehl:

flag provided but not defined: -machine_type

Dieser Fehler wird durch ein bekanntes Problem in den Apache Beam Go SDK-Versionen 2.47.0 und früher verursacht. Führen Sie zur Behebung dieses Problems ein Upgrade auf Apache Beam Go Version 2.48.0 oder höher durch.

JAR-Datei des Remote-Jobservers konnte nicht abgerufen werden

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, ohne mit dem Internet verbunden zu sein, schlägt der Job möglicherweise mit der folgenden Fehlermeldung fehl:

Unable to fetch remote job server jar at
https://repo.maven.apache.org/maven2/org/apache/beam/beam-sdks-java-io-expansion-service/VERSION/beam-sdks-java-io-expansion-service-VERSION.jar:
\u003curlopen error [Errno 101] Network is unreachable\u003e

Dieser Fehler tritt auf, weil die VM das Apache Beam-Java-Paket nicht aus dem Internet herunterladen kann. Dieses Paket ist erforderlich, wenn Sie einen mehrsprachigen Job mit einer flexiblen Vorlage ausführen.

Nehmen Sie eine der folgenden Änderungen vor, um dieses Problem zu beheben:

  • Internetverbindung herstellen Wenn eine Internetverbindung besteht, kann Ihr Job auf die erforderliche Datei zugreifen.

  • Fügen Sie das Apache Beam Java-Paket in Ihr lokales Verzeichnis ein, damit Ihr Job lokal darauf zugreifen kann. Erstellen Sie die Datei /root/.apache_beam/cache/jars/ im folgenden Verzeichnis: Beispiel: /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar

Dateisystem konnte nicht über den angegebenen Pfad abgerufen werden

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, schlägt der Job möglicherweise mit dem folgenden Fehler fehl:

ValueError: Unable to get filesystem from specified path, please use
the correct path or ensure the required dependency is installed, e.g., pip
install apache-beam[gcp]. Path specified: PATH

Dieser Fehler tritt auf, wenn für den Job ein Container-Image der flexiblen Vorlage verwendet wird und das Container-Image keine Java-Installation enthält.

Fügen Sie Ihrem Dockerfile die folgende Zeile hinzu, um dieses Problem zu beheben:

sh RUN apt-get update && apt-get install -y openjdk-17-jdk

Mit diesem Befehl wird Java in Ihrer Containerumgebung installiert.

Ressourcenerschöpfung der Launcher-VM

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, schlägt der Job möglicherweise mit dem folgenden Fehler fehl:

Failed to start the VM, launcher-ID, used for launching because of status code: INTERNAL, reason: Unknown error in operation 'OPERATION_ID': [ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS] 'The zone 'projects/PROJECT_ID/zones/ZONE_ID' does not have enough resources available to fulfill the request.

Der VM-Name launcher-ID steht für den Namen der Launcher-VM. Die Launcher-VM ist für das Erfassen von Jobressourcen wie dem Vorlagencode und dem Image verantwortlich, bevor der Jobgraph erstellt und an den Dataflow-Dienst gesendet wird, um die Arbeit zu starten.

Wenn Sie den Parameter launcherMachineType nicht angeben, wählt Dataflow einen Standardmaschinentyp für die Launcher-VM aus, in der Regel e2-standard-2. Diese Auswahl ist unabhängig vom Worker-machineType. Fehler aufgrund von Ressourcenerschöpfung können auftreten, wenn dieser Standardmaschinentyp in der Region oder Zone des Jobs nicht verfügbar ist. Wenn Sie einen bestimmten Maschinentyp verwenden möchten, legen Sie launcherMachineType fest.

Verwenden Sie eine der folgenden Strategien, um dieses Problem zu beheben:

  • Aktualisieren Sie den Maschinentyp des Launchers auf einen anderen Maschinentyp und wiederholen Sie den Job.
  • Wenn Sie den Parameter zone festgelegt haben, entfernen Sie ihn, damit Dataflow die Launcher-VM in einer Zone mit Kapazität platzieren kann.
  • Starten Sie Ihre flexible Vorlage aus einer anderen Region.

Verzögerung beim Starten der flexiblen Vorlage

Wenn Sie einen Job mit einer flexiblen Vorlage senden, wird die Jobanfrage in eine Spanner-Warteschlange gestellt. Der Vorlagen-Launcher ruft den Job aus der Spanner-Warteschlange ab und führt dann die Vorlage aus. Falls Spanner einen Nachrichtenrückstand hat, kann es zwischen dem Senden und dem Start des Jobs zu einer erheblichen Verzögerung kommen.

Um dieses Problem zu umgehen, starten Sie Ihre flexible Vorlage in einer anderen Region.

Die Vorlagenparameter sind ungültig

Wenn Sie versuchen, mit der gcloud CLI einen Job auszuführen, der eine von Google bereitgestellte Vorlage verwendet, tritt der folgende Fehler auf:

ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter

Dieser Fehler tritt auf, weil einige von Google bereitgestellten Vorlagen die Optionen defaultSdkHarnessLog und defaultWorkerLog nicht unterstützen.

Verwenden Sie die entsprechende Methode für Ihren Vorlagentyp, um dieses Problem zu beheben.

Flexible Vorlagen

Verwenden Sie bei flexiblen Vorlagen das Flag --additional-pipeline-options, um die Pipelineoptionen als String zu übergeben. Beispiel mit dem Befehl gcloud dataflow flex-template run:

gcloud dataflow flex-template run JOB_NAME \
--template-file-gcs-location=GCS_TEMPLATE_PATH \
--additional-pipeline-options=defaultSdkHarnessLogLevel=WARN,defaultWorkerLogLevel=WARN

Ersetzen Sie die folgenden Werte:

  • JOB_NAME: der Name Ihres Dataflow-Jobs
  • GCS_TEMPLATE_PATH: der Cloud Storage-Pfad zur Vorlagendatei
Klassische Vorlagen

Bei klassischen Vorlagen besteht die Problemumgehung darin, die Vorlagenspezifikationsdatei in einen Cloud Storage-Bucket zu kopieren und der Datei die folgenden zusätzlichen Parameter hinzuzufügen.

"metadata": {
    ...
    "parameters": [
      ...,
      {
        "name": "defaultSdkHarnessLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      },
      {
        "name": "defaultWorkerLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      }
    ]
  }

Nachdem Sie diese Änderung an der Vorlagendatei vorgenommen haben, verwenden Sie das folgende Flag, wenn Sie die Vorlage ausführen.

--gcs-location=gs://BUCKET_NAME/FILENAME

Ersetzen Sie die folgenden Werte:

  • BUCKET_NAME: der Name Ihres Cloud Storage-Buckets
  • FILENAME: durch den Name Ihrer Vorlagenspezifikationsdatei

Flexible Vorlage-Launcher-Logs zeigen den falschen Schweregrad an

Wenn die Ausführung einer benutzerdefinierten flexiblen Vorlage fehlschlägt, wird in den Logdateien die folgende Meldung mit dem Schweregrad ERROR angezeigt:

ERROR: Error occurred in the launcher container: Template launch failed. See console logs.

Die Ursache für den Startfehler wird in der Regel vor dieser Meldung mit dem Schweregrad INFO in den Logs angezeigt. Obwohl diese Logebene möglicherweise falsch ist, ist sie zu erwarten, da mit dem Launcher für Flexible Vorlage keine Schweregraddetails aus den von der Apache Beam-Anwendung generierten Logeinträgen extrahiert werden können.

Wenn Sie den korrekten Schweregrad für jede Nachricht im Launcher-Log sehen möchten, konfigurieren Sie Ihre Vorlage so, dass Logs im JSON-Format statt im Nur-Text-Format generiert werden. Mit dieser Konfiguration kann der Vorlagen-Launcher den korrekten Schweregrad der Logeinträge extrahieren. Verwenden Sie die folgende Nachrichtenstruktur:

{
  "message": "The original log message",
  "severity": "DEBUG/INFO/WARN/ERROR"
}

In Java können Sie den Logback-Logger mit einer benutzerdefinierten JSON-Appender-Implementierung verwenden. Weitere Informationen finden Sie in der Logback-Beispielkonfiguration und im JSON-Appender-Beispielcode auf GitHub.

Dieses Problem betrifft nur die Logs, die vom Launcher der flexiblen Vorlage beim Starten der Pipeline generiert werden. Wenn der Start erfolgreich war und die Pipeline ausgeführt wird, haben die von Dataflow-Workern erstellten Logs den korrekten Schweregrad.

Von Google bereitgestellte Vorlagen zeigen beim Start des Jobs den richtigen Schweregrad an, da die von Google bereitgestellten Vorlagen diesen JSON-Logging-Ansatz verwenden.