Jobs durch Ausführen von dsub-Pipelines in Batch orchestrieren

---

In dieser Anleitung wird erläutert, wie Sie eine dsub-Pipeline in Batch ausführen. Im Einzelnen verarbeitet die Beispielpipeline dsub DNA-Sequenzierungsdaten in einer BAM-Datei (Binary Targeting Map), um eine BAM-Indexdatei (BAI) zu erstellen.

Diese Anleitung richtet sich an Batch-Nutzer, die dsub mit Batch verwenden möchten. dsub ist ein Open-Source-Jobplaner zur Orchestrierung von Batchverarbeitungsworkflows in Google Cloud. Weitere Informationen zur Verwendung von Batch mit dsub finden Sie in der dsub-Dokumentation zu Batch.

Lernziele

• Führen Sie eine dsub-Pipeline in Batch aus, die Dateien in Cloud Storage-Buckets liest und schreibt.
• Sehen Sie sich die Ausgabedateien in einem Cloud Storage-Bucket an.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

• Batch
• Cloud Storage

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Die in dieser Anleitung erstellten Ressourcen kosten in der Regel weniger als einen Dollar, vorausgesetzt, Sie führen alle Schritte – einschließlich der Bereinigung – rechtzeitig durch.

Hinweise

1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
2. Installieren Sie die Google Cloud CLI.

3. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:

   gcloud init

4. Google Cloud-Projekt erstellen oder auswählen.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   • Erstellen Sie ein Google Cloud-Projekt:

     gcloud projects create PROJECT_ID

     Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud-Projekt, das Sie erstellen.

   • Wählen Sie das von Ihnen erstellte Google Cloud-Projekt aus:

     gcloud config set project PROJECT_ID

     Ersetzen Sie PROJECT_ID durch den Namen Ihres Google Cloud-Projekts.

5. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

6. Aktivieren Sie die Batch, Cloud Storage, Compute Engine, and Logging APIs:

   gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

7. Installieren Sie die Google Cloud CLI.

8. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:

   gcloud init

9. Google Cloud-Projekt erstellen oder auswählen.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   • Erstellen Sie ein Google Cloud-Projekt:

     gcloud projects create PROJECT_ID

     Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud-Projekt, das Sie erstellen.

   • Wählen Sie das von Ihnen erstellte Google Cloud-Projekt aus:

     gcloud config set project PROJECT_ID

     Ersetzen Sie PROJECT_ID durch den Namen Ihres Google Cloud-Projekts.

10. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

11. Aktivieren Sie die Batch, Cloud Storage, Compute Engine, and Logging APIs:

    gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

12. Achten Sie darauf, dass Ihr Projekt mindestens ein Dienstkonto mit den für diese Anleitung erforderlichen Berechtigungen hat.

    Hinweis: Wenn Sie ein neues Projekt verwenden, ist dieser Schritt nur erforderlich, wenn Ihre Organisation automatische Rollenzuweisungen für Standarddienstkonten verhindert. Standardmäßig wird dem Compute Engine-Standarddienstkonto automatisch die IAM-Rolle „Bearbeiter“ (roles/editor) zugewiesen, die bereits alle für diese Anleitung erforderlichen Berechtigungen hat.

    Für jeden Job ist ein Dienstkonto erforderlich, mit dem der Batch-Dienst-Agent die zum Ausführen des Jobs erforderlichen Ressourcen erstellen und darauf zugreifen kann. In dieser Anleitung ist das Dienstkonto des Jobs das Compute Engine-Standarddienstkonto.

    Bitten Sie Ihren Administrator, dem Compute Engine-Standarddienstkonto die folgenden IAM-Rollen zu gewähren, damit das Compute Engine-Standarddienstkonto die erforderlichen Berechtigungen hat, damit der Batch-Dienst-Agent Ressourcen für Batch-Jobs erstellen und darauf zugreifen kann:

    • Batch Agent Reporter (roles/batch.agentReporter) für das Projekt
    • Storage Admin (roles/storage.admin) für das Projekt
    • (Empfohlen) Lassen Sie Jobs Logs in Cloud Logging generieren: Logautor (roles/logging.logWriter) für das Projekt

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

    Möglicherweise kann Ihr Administrator dem Compute Engine-Standarddienstkonto auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen die erforderlichen Berechtigungen erteilen.

13. Prüfen Sie, ob Sie die für diese Anleitung erforderlichen Berechtigungen haben.

    Hinweis: Wenn Sie dieses Projekt erstellt haben, ist dieser Schritt nicht erforderlich. Als Projektersteller wird Ihnen automatisch die IAM-Rolle "Inhaber" (roles/owner) zugewiesen, die bereits alle für diese Anleitung erforderlichen Berechtigungen hat.

    Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zu gewähren, damit Sie die Berechtigungen erhalten, die Sie zum Ausführen dieser Anleitung benötigen:

    • Batch Job Editor (roles/batch.jobsEditor) für das Projekt
    • Dienstkontonutzer (roles/iam.serviceAccountUser) für das Dienstkonto des Jobs. In dieser Anleitung ist es das Compute Engine-Standarddienstkonto.
    • Storage-Objekt-Administrator (roles/storage.objectAdmin) für das Projekt

14. Installieren Sie dsub und die zugehörigen Abhängigkeiten. Weitere Informationen finden Sie in der Installationsdokumentation für dsub.

    1. Prüfen Sie, ob Versionen von Python und pip installiert sind, die von der neuesten Version von dsub unterstützt werden. Führen Sie den folgenden Befehl aus, um die aktuell installierten Versionen aufzurufen:

       pip --version
       

       Wenn Sie pip oder Python installieren oder aktualisieren müssen, führen Sie die Schritte zur Installation von Python aus.

    2. Empfohlen: Erstellen und aktivieren Sie eine virtuelle Python-Umgebung, um Fehler aufgrund von Abhängigkeitskonflikten bei der Installation von dsub zu vermeiden:

       python -m venv dsub_libs && source dsub_libs/bin/activate
       

    3. Klonen Sie das GitHub-Repository dsub mit git und öffnen Sie es:

       git clone https://github.com/databiosphere/dsub.git && cd dsub
       

    4. Installieren Sie dsub und die zugehörigen Abhängigkeiten:

       python -m pip install .
       

       Die Ausgabe sieht in etwa so aus:

       ...
       Successfully installed cachetools-5.3.1 certifi-2023.7.22 charset-normalizer-3.3.1 dsub-0.4.9 funcsigs-1.0.2 google-api-core-2.11.0 google-api-python-client-2.85.0 google-auth-2.17.3 google-auth-httplib2-0.1.0 google-cloud-batch-0.10.0 googleapis-common-protos-1.61.0 grpcio-1.59.0 grpcio-status-1.59.0 httplib2-0.22.0 idna-3.4 mock-4.0.3 parameterized-0.8.1 proto-plus-1.22.3 protobuf-4.24.4 pyasn1-0.4.8 pyasn1-modules-0.2.8 pyparsing-3.1.1 python-dateutil-2.8.2 pytz-2023.3 pyyaml-6.0 requests-2.31.0 rsa-4.9 six-1.16.0 tabulate-0.9.0 tenacity-8.2.2 uritemplate-4.1.1 urllib3-2.0.7
       

Cloud Storage-Bucket erstellen

Führen Sie den Befehl gcloud storage buckets create aus, um einen Cloud Storage-Bucket zum Speichern der Ausgabedateien aus der Beispielpipeline dsub mithilfe der gcloud CLI zu erstellen:

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

Ersetzen Sie Folgendes:

• BUCKET_NAME ist ein global eindeutiger Name für den Bucket.

• PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

Die Ausgabe sieht in etwa so aus:

Creating gs://BUCKET_NAME/...

dsub-Pipeline ausführen

Die Beispielpipeline dsub indexiert eine BAM-Datei aus dem 1.000 Genomes-Projekt und gibt die Ergebnisse in einen Cloud Storage-Bucket aus.

Führen Sie den folgenden dsub-Befehl aus, um die dsub-Beispielpipeline auszuführen:

dsub \
    --provider google-batch \
    --project PROJECT_ID \
    --logging gs://BUCKET_NAME/WORK_DIRECTORY/logs \
    --input BAM=gs://genomics-public-data/1000-genomes/bam/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam \
    --output BAI=gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai \
    --image quay.io/cancercollaboratory/dockstore-tool-samtools-index \
    --command 'samtools index ${BAM} ${BAI}' \
    --wait

Ersetzen Sie Folgendes:

• PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

• BUCKET_NAME: der Name des von Ihnen erstellten Cloud Storage-Buckets.

• WORK_DIRECTORY: der Name für ein neues Verzeichnis, in dem die Pipeline Logs und Ausgaben speichern kann. Geben Sie beispielsweise workDir ein.

Die dsub-Pipeline führt einen Batch-Job aus, der die BAI-Datei und die Logs in das angegebene Verzeichnis in Ihrem Cloud Storage-Bucket schreibt. Insbesondere enthält das Repository dsub ein vordefiniertes Docker-Image, das mit samtools die BAM-Datei indexiert, die Sie im Flag --input angegeben haben.

Der Befehl wird erst abgeschlossen, wenn die Pipeline dsub ausgeführt wurde. Dies hängt davon ab, wann der Batchjob geplant ist. Dies dauert in der Regel etwa 10 Minuten: Batch beginnt normalerweise innerhalb weniger Minuten mit der Ausführung des Jobs. Die Laufzeit des Jobs beträgt etwa 8 Minuten.

Zuerst wird der Befehl noch ausgeführt und die Ausgabe sieht in etwa so aus:

Job properties:
  job-id: JOB_NAME
  job-name: samtools
  user-id: USERNAME
Provider internal-id (operation): projects/PROJECT_ID/locations/us-central1/jobs/JOB_NAME
Launched job-id: JOB_NAME
To check the status, run:
  dstat --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME' --status '*'
To cancel the job, run:
  ddel --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME'
Waiting for job to complete...
Waiting for: JOB_NAME.

Wenn der Job erfolgreich abgeschlossen wurde, wird der Befehl beendet und die Ausgabe sieht in etwa so aus:

  JOB_NAME: SUCCESS
JOB_NAME

Diese Ausgabe enthält die folgenden Werte:

• JOB_NAME: der Name des Jobs.

• USERNAME: Ihr Google Cloud-Nutzername.

• PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

Ausgabedateien ansehen

Zum Aufrufen der Ausgabedateien, die von der Beispielpipeline dsub mithilfe der gcloud CLI erstellt wurden, führen Sie den Befehl gcloud storage ls aus:

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

Ersetzen Sie Folgendes:

• BUCKET_NAME: der Name des von Ihnen erstellten Cloud Storage-Buckets.

• WORK_DIRECTORY: das Verzeichnis, das Sie im Befehl dsub angegeben haben.

• PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

Die Ausgabe sieht in etwa so aus:

gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/

Diese Ausgabe enthält die BAI-Datei und ein Verzeichnis mit den Logs des Jobs.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten durch Löschen des aktuellen Projekts.

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

Google Cloud-Projekt löschen:

gcloud projects delete PROJECT_ID

Einzelne Ressourcen löschen

Wenn Sie das aktuelle Projekt weiterhin verwenden möchten, löschen Sie die einzelnen in dieser Anleitung verwendeten Ressourcen.

Bucket löschen

Nachdem die Pipeline ausgeführt wurde, erstellt sie Ausgabedateien und speichert sie im Verzeichnis WORK_DIRECTORY Ihres Cloud Storage-Buckets.

Führen Sie einen der folgenden Schritte aus, um die Kosten für Cloud Storage für das aktuelle Google Cloud-Konto zu reduzieren:

• Wenn Sie den in dieser Anleitung verwendeten Bucket nicht mehr benötigen, löschen Sie den Bucket und seinen gesamten Inhalt mit dem Befehl gcloud storage rm mit dem Flag --recursive:

  gcloud storage rm gs://BUCKET_NAME \
      --recursive \
      --project PROJECT_ID
  

  Ersetzen Sie Folgendes:

  • BUCKET_NAME: der Name des von Ihnen erstellten Cloud Storage-Buckets.

  • PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

• Wenn Sie den Bucket weiterhin benötigen, verwenden Sie den Befehl gcloud storage rm mit dem Flag --recursive, um nur das Verzeichnis WORK_DIRECTORY und seinen gesamten Inhalt zu löschen:

  gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
      --recursive \
      --project PROJECT_ID
  

  Ersetzen Sie Folgendes:

  • BUCKET_NAME: der Name des von Ihnen erstellten Cloud Storage-Buckets.

  • WORK_DIRECTORY: das Verzeichnis, das Sie im Befehl dsub angegeben haben.

  • PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

Job löschen

Führen Sie den Befehl gcloud batch jobs delete aus, um einen Job über die gcloud CLI zu löschen.

gcloud batch jobs delete JOB_NAME \
    --location us-central1 \
    --project PROJECT_ID

Ersetzen Sie Folgendes:

• JOB_NAME: der Name des Jobs.
• PROJECT_ID: die Projekt-ID Ihres Google Cloud-Projekts.

Nächste Schritte

• Weitere Informationen zu dsub und dsub für Batch.
• Weitere Informationen zur Verwendung von Speicher-Volumes mit Batch