Jobs mit dsub-Pipelines in Batch orchestrieren

---

In dieser Anleitung wird beschrieben, wie Sie eine dsub-Pipeline in Batch ausführen. Insbesondere verarbeitet die Beispiel-dsub-Pipeline DNA-Sequenzdaten in einer BAM-Datei (Binary Alignment Map), um eine BAM-Indexdatei (BAI) zu erstellen.

Diese Anleitung richtet sich an Nutzer von Batch, die dsub mit Batch verwenden möchten. dsub ist ein Open-Source-Job-Scheduler zur Orchestration von Batchverarbeitungsworkflows in Google Cloud. Weitere Informationen zur Verwendung von Batch mit dsub finden Sie in der dsub-Dokumentation für Batch.

Lernziele

• Eine dsub-Pipeline in Batch ausführen, die Dateien in Cloud Storage-Buckets liest und schreibt
• Rufen Sie die Ausgabedateien in einem Cloud Storage-Bucket auf.

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, zeitnah durch.

Hinweise

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

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

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

10. Make sure that billing is enabled for your Google Cloud project.

11. Enable the 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 nicht erforderlich,es sei denn, Ihre Organisation verhindert automatische Rollenzuweisungen für Standarddienstkonten. Dem Compute Engine-Standarddienstkonto wird standardmäßig automatisch die IAM-Rolle „Bearbeiter“ (roles/editor) zugewiesen. Diese Rolle hat bereits alle Berechtigungen, die für diese Anleitung erforderlich sind.

    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.

    Damit das Compute Engine-Standarddienstkonto die erforderlichen Berechtigungen hat, um dem Batch-Dienst-Agent das Erstellen und den Zugriff auf Ressourcen für Batch-Jobs zu ermöglichen, bitten Sie Ihren Administrator, dem Compute Engine-Standarddienstkonto die folgenden IAM-Rollen zu erteilen:

    • Batch-Agent-Melder (roles/batch.agentReporter) für das Projekt
    • Storage-Administrator (roles/storage.admin) für das Projekt
    • (Empfohlen) Jobs Logs in Cloud Logging generieren lassen: Log-Autor (roles/logging.logWriter) für das Projekt

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

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

13. Sie benötigen die für diese Anleitung erforderlichen Berechtigungen.

    Hinweis:Wenn Sie dieses Projekt erstellt haben, ist dieser Schritt nicht erforderlich. Als Projektersteller erhalten Sie automatisch die IAM-Rolle „Inhaber“ (roles/owner), die bereits alle für dieses Tutorial erforderlichen Berechtigungen enthält.

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

    • Batch-Job-Bearbeiter (roles/batch.jobsEditor) für das Projekt
    • Dienstkontonutzer (roles/iam.serviceAccountUser) für das Dienstkonto des Jobs, in diesem Fall 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 Installationsanleitung für dsub.

    1. Sie benötigen Versionen von Python und pip, 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öchten, folgen Sie der Anleitung zum Installieren von Python.

    2. Empfohlen: Um Abhängigkeitskonfliktfehler bei der Installation von dsub zu vermeiden, erstellen und aktivieren Sie eine virtuelle Python-Umgebung:

       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 mit der gcloud CLI einen Cloud Storage-Bucket zum Speichern der Ausgabedateien aus der Beispiel-dsub-Pipeline zu erstellen:

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

Ersetzen Sie Folgendes:

• BUCKET_NAME: Ein global eindeutiger Name für Ihren 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 Project und gibt die Ergebnisse in einem Cloud Storage-Bucket aus.

Führen Sie den folgenden dsub-Befehl aus, um die Beispiel-dsub-Pipeline 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 eines neuen Verzeichnisses, in dem die Pipeline Protokolle und Ausgaben speichern kann. Geben Sie beispielsweise workDir ein.

In der dsub-Pipeline wird ein Batchjob ausgeführt, der die BAI-Datei und die Protokolle in das angegebene Verzeichnis in Ihrem Cloud Storage-Bucket schreibt. Das dsub-Repository enthält ein vorkonfiguriertes Docker-Image, das samtools verwendet, um die BAM-Datei zu indexieren, die Sie im Flag --input angegeben haben.

Der Befehl wird erst beendet, wenn die Ausführung der dsub-Pipeline abgeschlossen ist. Das kann je nach Planung des Batchjobs variieren. Das dauert in der Regel etwa 10 Minuten: Der Batchjob wird in der Regel innerhalb weniger Minuten gestartet und dauert 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.

Nach Abschluss des Jobs 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

Wenn Sie die Ausgabedateien aufrufen möchten, die von der Beispiel-dsub-Pipeline mit 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 Protokollen 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, indem Sie das aktuelle Projekt löschen.

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.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Einzelne Ressourcen löschen

Wenn Sie das aktuelle Projekt weiter verwenden möchten, löschen Sie die einzelnen Ressourcen, die in dieser Anleitung verwendet wurden.

Bucket löschen

Nach Abschluss der Ausführung der Pipeline werden Ausgabedateien im Verzeichnis WORK_DIRECTORY Ihres Cloud Storage-Buckets erstellt und gespeichert.

So reduzieren Sie die Cloud Storage-Gebühren für das aktuelleGoogle Cloud- -Konto:

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

  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 jedoch noch 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

Wenn Sie einen Job mit der gcloud CLI löschen möchten, führen Sie den Befehl gcloud batch jobs delete aus.

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 Speichervolumes mit Batch