Jobs mit dsub-Pipelines in Batch orchestrieren

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

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

Ziele

• Eine dsub-Pipeline in Batch ausführen, 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 Nutzern von Google Cloud 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 aus.

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch 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.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

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.

• So 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 Projekts in Google Cloud .

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die Batch API, die Cloud Storage API, die Compute Engine API und die Logging API:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

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

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

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.

• So 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 Projekts in Google Cloud .

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die Batch API, die Cloud Storage API, die Compute Engine API und die Logging API:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

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

1. 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 die automatische Rollenzuweisung für Standarddienstkonten. 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 zuzuweisen, damit das Compute Engine-Standarddienstkonto die erforderlichen Berechtigungen hat, damit der Batch-Dienst-Agent Ressourcen für Batch-Jobs erstellen und darauf zugreifen kann:

   Wichtig:Sie müssen diese Rollen dem Compute Engine-Standarddienstkonto und nicht Ihrem Nutzerkonto zuweisen. Wenn die Rollen nicht dem richtigen Hauptkonto zugewiesen werden, können Berechtigungsfehler auftreten.
   • 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 Compute Engine-Standarddienstkonto möglicherweise auch die erforderlichen Berechtigungen über benutzerdefinierte Rollen oder andere vordefinierte Rollen erteilen.

2. 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 Ersteller des Projekts wird Ihnen automatisch die IAM-Rolle „Inhaber“ (roles/owner) zugewiesen, 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-Editor (roles/batch.jobsEditor) für das Projekt
   • Dienstkontonutzer (roles/iam.serviceAccountUser) für das Dienstkonto des Jobs, das in dieser Anleitung das Compute Engine-Standarddienstkonto ist
   • Storage-Objekt-Administrator (roles/storage.objectAdmin) für das Projekt

3. Installieren Sie dsub und die zugehörigen Abhängigkeiten. Weitere Informationen finden Sie in der Installationsdokumentation zu dsub.

   1. Achten Sie darauf, dass Sie Versionen von Python und pip installiert haben, die von der aktuellen 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, folgen Sie der Anleitung zum Installieren von Python.

   2. Empfohlen: Um Fehler durch Abhängigkeitskonflikte 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 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 gcloud storage buckets create-Befehl aus, um mit der gcloud CLI einen Cloud Storage-Bucket zum Speichern der Ausgabedateien aus der Beispielpipeline dsub 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 etwa so aus:

Creating gs://BUCKET_NAME/...

dsub-Pipeline ausführen

In der Beispielpipeline dsub wird eine BAM-Datei aus dem 1000 Genomes Project indexiert und die Ergebnisse werden in einen Cloud Storage-Bucket ausgegeben.

Führen Sie zum Ausführen der dsub-Beispielpipeline den folgenden dsub-Befehl aus:

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 Cloud Storage-Buckets, den Sie erstellt haben.

• WORK_DIRECTORY: Der Name eines neuen Verzeichnisses, in dem die Pipeline Logs und Ausgaben speichern kann. Geben Sie beispielsweise workDir ein.

Die Pipeline dsub führt einen Batchjob aus, der die BAI-Datei und die Logs in das angegebene Verzeichnis in Ihrem Cloud Storage-Bucket schreibt. Das Repository dsub enthält ein vorgefertigtes 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 dsub-Pipeline abgeschlossen ist. Das kann je nach Zeitplan des Batchjobs variieren. Normalerweise dauert das etwa 10 Minuten: Batch beginnt in der Regel innerhalb weniger Minuten mit der Ausführung des Jobs und 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

Führen Sie den Befehl gcloud storage ls aus, um die Ausgabedateien aufzurufen, die von der dsub-Beispielpipeline mit der gcloud CLI erstellt wurden:

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

Ersetzen Sie Folgendes:

• BUCKET_NAME: Der Name des Cloud Storage-Buckets, den Sie erstellt haben.

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

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

Die Ausgabe sieht 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, wenn 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, zum Beispiel eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, anstatt 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 Ressourcen, die in dieser Anleitung verwendet wurden.

Bucket löschen

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

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

• Wenn Sie den in dieser Anleitung verwendeten Bucket nicht mehr benötigen, verwenden Sie den gcloud storage rm-Befehl 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 Cloud Storage-Buckets, den Sie erstellt haben.

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

• Wenn Sie den Bucket weiterhin benötigen, verwenden Sie den gcloud storage rm-Befehl 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 Cloud Storage-Buckets, den Sie erstellt haben.

  • 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 zum Löschen eines Jobs mit der gcloud CLI 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