Nextflow ausführen

Auf dieser Seite wird erläutert, wie Sie mit Nextflow eine Pipeline in Google Cloud ausführen.

Die in dieser Anleitung verwendete Pipeline ist ein Proof of Concept für eine RNA-Seq-Pipeline, mit der die Nextflow-Nutzung in Google Cloud veranschaulicht werden soll.

Ziele

Nach Abschluss dieser Anleitung beherrschen Sie Folgendes:

Installieren Sie Nextflow in Cloud Shell.
Nextflow-Pipeline konfigurieren
Pipeline mit Nextflow in Google Cloud ausführen

Kosten

In dieser Anleitung werden kostenpflichtige Komponenten von Google Cloud verwendet, darunter:

Compute Engine
Cloud Storage

Der Preisrechner kann eine Kostenschätzung anhand Ihrer voraussichtlichen Nutzung generieren. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweis

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.

Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

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.

Zur Projektauswahl

Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für Ihr Projekt aktiviert ist.

Cloud Life Sciences, Compute Engine, and Cloud Storage APIs aktivieren.
Aktivieren Sie die APIs

Cloud Storage-Bucket erstellen

Erstellen Sie einen eindeutig benannten Bucket, in den im Verlauf der Anleitung temporäre Arbeiten und Ausgabedateien gespeichert werden. Beachten Sie dabei die Benennungsrichtlinien für Buckets: Wie in den Benennungsrichtlinien für Buckets beschrieben, funktioniert diese Anleitung für die DNS-Kompatibilität nicht mit Bucket-Namen, die einen Unterstrich (_) enthalten.

Console

Öffnen Sie in der Cloud Console den Cloud Storage-Browser:

Zum Cloud Storage Browser
Klicken Sie auf Bucket erstellen.
Geben Sie im Textfeld Bucket-Name einen eindeutigen Namen für Ihren Bucket ein und klicken Sie auf Erstellen.

gcloud

Öffnen Sie Cloud Shell:

Zu Cloud Shell
Führen Sie folgenden Befehl aus, um einen Bucket zu erstellen. Ersetzen Sie dabei BUCKET durch einen eindeutigen Namen für den Bucket.
```
gsutil mb gs://BUCKET
```

Dienstkonto erstellen und Rollen hinzufügen

Führen Sie die folgenden Schritte aus, um ein Dienstkonto zu erstellen und die relevanten IAM-Rollen hinzuzufügen:

Console

Erstellen Sie mit der Cloud Console ein Dienstkonto:

Rufen Sie in der Cloud Console die Seite Dienstkonten auf.

Zur Seite „Dienstkonten“
Klicken Sie auf Dienstkonto erstellen.
Geben Sie im Feld Name des Dienstkontos nextflow-service-account ein und klicken Sie dann auf Erstellen.
Geben Sie im Abschnitt Diesem Dienstkonto Zugriff auf das Projekt erteilen die folgenden Rollen aus der Drop-down-Liste Rolle auswählen ein:
- Cloud Life Sciences-Workflows-Runner
- Dienstkontonutzer
- Service Usage-Nutzer
- Storage-Objekt-Administrator
Klicken Sie auf Weiter und dann auf Fertig.
Suchen Sie auf der Seite "Dienstkonten" das Dienstkonto, das Sie erstellt haben. Klicken Sie in der Zeile des Dienstkontos auf die Schaltfläche und anschließend auf Schlüssel verwalten.
Klicken Sie auf der Seite Schlüssel auf Schlüssel hinzufügen und dann auf Neuen Schlüssel erstellen.
Wählen Sie als Schlüsseltyp JSON aus und klicken Sie auf Erstellen.

Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

gcloud

Führen Sie die folgenden Schritte in Cloud Shell aus:

Cloud Shell öffnen

Zu Cloud Shell

Legen Sie die Variablen fest, die beim Erstellen des Dienstkontos verwendet werden sollen. Ersetzen Sie dabei PROJECT_ID durch Ihre Projekt-ID.

export PROJECT=PROJECT_ID
export SERVICE_ACCOUNT_NAME=nextflow-service-account
export SERVICE_ACCOUNT_ADDRESS=${SERVICE_ACCOUNT_NAME}@${PROJECT}.iam.gserviceaccount.com

Erstellen Sie das Dienstkonto.

gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

Das Dienstkonto benötigt folgende Rollen für die Identitäts- und Zugriffsverwaltung:

roles/lifesciences.workflowsRunner
roles/iam.serviceAccountUser
roles/serviceusage.serviceUsageConsumer
roles/storage.objectAdmin

Weisen Sie diese Rollen durch Ausführen folgender Befehle in Cloud Shell zu:

gcloud projects add-iam-policy-binding ${PROJECT} \
    --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
    --role roles/lifesciences.workflowsRunner

gcloud projects add-iam-policy-binding ${PROJECT} \
    --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
    --role roles/iam.serviceAccountUser

gcloud projects add-iam-policy-binding ${PROJECT} \
    --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
    --role roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding ${PROJECT} \
    --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
    --role roles/storage.objectAdmin

Anmeldedaten für Ihre Anwendung angeben

Sie können Anmeldedaten zur Authentifizierung für Ihren Anwendungscode oder Ihre Befehle angeben. Legen Sie hierfür die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Dateipfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält.

In den folgenden Schritten wird gezeigt, wie Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen:

Console

Cloud Shell öffnen

Zu Cloud Shell
Wählen Sie im Cloud Shell-Menü Mehr die Option Datei hochladen und dann die soeben erstellte JSON-Schlüsseldatei aus. Mit diesem Schritt wird die Datei in das Basisverzeichnis Ihrer Cloud Shell-Instanz hochgeladen.
Bestätigen Sie, dass sich die hochgeladene Datei in Ihrem aktuellen Verzeichnis befindet, und bestätigen Sie den Dateinamen. Führen Sie dafür den folgenden Befehl aus:
```
ls
```
Legen Sie die Anmeldedaten fest und ersetzen Sie dabei KEY-FILENAME.json durch den Namen Ihrer Schlüsseldatei.
```
export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY-FILENAME.json
```

gcloud

Führen Sie die folgenden Schritte in Cloud Shell aus:

Cloud Shell öffnen

Zu Cloud Shell

Legen Sie die private Schlüsseldatei auf die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS fest:

export SERVICE_ACCOUNT_KEY=${SERVICE_ACCOUNT_NAME}-private-key.json
gcloud iam service-accounts keys create \
  --iam-account=${SERVICE_ACCOUNT_ADDRESS} \
  --key-file-type=json ${SERVICE_ACCOUNT_KEY}
export SERVICE_ACCOUNT_KEY_FILE=${PWD}/${SERVICE_ACCOUNT_KEY}
export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/${SERVICE_ACCOUNT_KEY}

NextFlow in Cloud Shell installieren und konfigurieren

Damit Sie keine Software auf Ihrem Computer installieren müssen, führen Sie alle Terminalbefehle in dieser Anleitung in Cloud Shell aus.

Falls noch nicht geschehen, öffnen Sie Cloud Shell.

Zu Cloud Shell

Führen Sie folgende Befehle aus, um Nextflow zu installieren:

export NXF_VER=20.10.0
export NXF_MODE=google
curl https://get.nextflow.io | bash

Wenn die Installation erfolgreich abgeschlossen wurde, wird folgende Meldung angezeigt:

    N E X T F L O W
version 20.10.0 build 5430
created 01-11-2020 15:14 UTC (10:14 EDT)
cite doi:10.1038/nbt.3820
http://nextflow.io

Nextflow installation completed. Please note:
‐ the executable file `nextflow` has been created in the folder: DIRECTORY
‐ you may complete the installation by moving it to a directory in your $PATH

Führen Sie den folgenden Befehl aus, um das Beispiel-Pipeline-Repository zu klonen. Das Repository enthält die auszuführende Pipeline und die von der Pipeline verwendeten Beispieldaten.
```
git clone https://github.com/nextflow-io/rnaseq-nf.git
```
Zum Konfigurieren von Nextflow führen Sie folgende Schritte aus:
1. Wechseln Sie in den Ordner rnaseq-nf.
```
cd rnaseq-nf
git checkout v2.0
```
2. Bearbeiten Sie die Datei nextflow.config mit einem beliebigen Texteditor und führen Sie die folgenden Aktualisierungen in dem Abschnitt mit der Bezeichnung gls aus:
  - Fügen Sie die Zeile google.project hinzu, falls es nicht vorhanden ist.
  - Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.
  - Ändern Sie bei Bedarf den Wert von google.location. Dieser muss einer der derzeit verfügbaren Cloud Life Sciences API-Standorte sein.
  - Ändern Sie bei Bedarf den Wert von google.region. Er gibt die Region an, in der die Compute Engine-VMs gestartet werden. Siehe verfügbare Compute Engine-Regionen und -Zonen.
  - Ersetzen Sie BUCKET durch den oben erstellten Bucket-Namen.
  - Ersetzen Sie WORK_DIR durch den Namen des Ordners, der für Protokollierung und Ausgabe verwendet werden soll. Verwenden Sie einen neuen Verzeichnisnamen, der in Ihrem Bucket noch nicht vorhanden ist.
  - Hinweis: Der Speicherort der Variablen workDir muss mindestens ein Unterverzeichnis enthalten. Verwenden Sie nicht nur den Bucket-Namen.
```
gls {
   params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'
   params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'
   params.multiqc = 'gs://rnaseq-nf/multiqc'
   process.executor = 'google-lifesciences'
   process.container = 'nextflow/rnaseq-nf:latest'
   workDir = 'gs://BUCKET/WORK_DIR'
   google.location = 'europe-west2'
   google.region  = 'europe-west1'
   google.project = 'PROJECT_ID'
}
```
3. Wechseln Sie zurück zum vorherigen Ordner.
```
cd ..
```

Führen Sie die Pipeline mit Nextflow aus.

Führen Sie die Pipeline mit Nextflow aus. Nach dem Start der Pipeline wird die Pipeline im Hintergrund ausgeführt, bis sie abgeschlossen ist. Es kann bis zu 10 Minuten dauern, bis die Pipeline abgeschlossen ist.

./nextflow run rnaseq-nf/main.nf -profile gls

Wenn die Pipeline abgeschlossen ist, wird folgende Meldung angezeigt:

N E X T F L O W  ~  version 20.10.0
Launching `rnaseq-nf/main.nf` [suspicious_mestorf] - revision: ef908c0bfd
R N A S E Q - N F   P I P E L I N E
 ===================================
 transcriptome: gs://rnaseq-nf/data/ggal/transcript.fa
 reads        : gs://rnaseq-nf/data/ggal/gut_{1,2}.fq
 outdir       : results
executor >  google-lifesciences (4)
[db/2af640] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[a6/927725] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[59/438177] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/9743b9] process > MULTIQC                       [100%] 1 of 1 ✔
Done! Open the following report in your browser --> results/multiqc_report.html
Completed at: DATE TIME
Duration    : 10m
CPU hours   : 0.2
Succeeded   : 4

Ausgabe der Nextflow-Pipeline anzeigen lassen

Nach Abschluss der Pipeline können Sie die Ausgabe sowie alle Logs, Fehler, ausgeführten Befehle und temporären Dateien prüfen.

Die Pipeline speichert die endgültige Ausgabedatei results/qc_report.html in dem Cloud Storage-Bucket, den Sie in der Datei nextflow.config angegeben haben.

Führen Sie folgende Schritte aus, um einzelne Ausgabedateien der einzelnen Aufgaben und Zwischendateien zu prüfen:

Console

Öffnen Sie in der Cloud Storage-Konsole die Seite Storage-Browser:

Zum Cloud Storage Browser
Rufen Sie BUCKET auf und gehen Sie zum WORK_DIR, das in der Datei nextflow.config angegeben ist.
Für jede Aufgabe, die in der Pipeline ausgeführt wurde, gibt es einen Ordner.
Der Ordner enthält die ausgeführten Befehle, die Ausgabedateien und die temporären Dateien, die während des Workflows verwendet wurden.

gcloud

Öffnen Sie Cloud Shell, um die Ausgabedateien in Cloud Shell anzuzeigen:

Zu Cloud Shell
Führen Sie den folgenden Befehl aus, um die Ausgaben in Ihrem Cloud Storage-Bucket aufzulisten. Aktualisieren Sie BUCKET und WORK_DIR in die in der Datei nextflow.config angegebenen Variablen.
```
gsutil ls gs://BUCKET/WORK_DIR
```
In der Ausgabe wird für jede ausgeführte Aufgabe ein Ordner angezeigt. Listen Sie auch den Inhalt der nachfolgenden Unterverzeichnisse auf, damit Sie alle von der Pipeline erstellten Dateien sehen können. Aktualisieren Sie TASK_FOLDER auf einen der mit dem obigen Befehl aufgelisteten Aufgabenordner.
```
gsutil ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER
```

Sie können sich die Zwischendateien ansehen, die von der Pipeline erstellt wurden, und entscheiden, welche Sie behalten möchten. Alternativ können Sie die Dateien entfernen, um die mit Cloud Storage verbundenen Kosten zu reduzieren. Informationen zum Entfernen der Dateien finden Sie unter Zwischendateien in einem Cloud Storage-Bucket entfernen.

Fehlerbehebung

Informationen zu Problemen beim Ausführen der Pipeline finden Sie unter Cloud Life Sciences API – Fehlerbehebung.
Wenn Ihre Pipeline nicht erfolgreich ausgeführt werden konnte, können Sie die Logs der jeweiligen Aufgaben überprüfen. Sehen Sie sich hierzu die Logdateien in den einzelnen Ordnern in Cloud Storage an, z. B. .command.err, .command.log, .command.out und so weiter.

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.

Nachdem Sie die Anleitung mit den Best Practices zum Ausführen der GATK-Pipeline abgeschlossen haben, können Sie die in Google Cloud erstellten Ressourcen bereinigen, damit sie kein Kontingent mehr in Anspruch nehmen und Ihnen in Zukunft nicht mehr in Rechnung gestellt werden. In den folgenden Abschnitten erfahren Sie, wie Sie diese Ressourcen löschen oder deaktivieren.

Zwischendateien im Cloud Storage-Bucket löschen

Die Pipeline speichert während der Ausführung Zwischendateien in gs://BUCKET/WORK_DIR. Sie können die Dateien nach Abschluss des Workflows entfernen, um die Kosten für Cloud Storage zu reduzieren.

So zeigen Sie den im Verzeichnis verwendeten Speicherplatz an:

gsutil du -sh gs://BUCKET/WORK_DIR

So entfernen Sie Dateien aus dem Arbeitsverzeichnis:

Console

Öffnen Sie in der Cloud Storage-Konsole die Seite Storage-Browser:

Zum Cloud Storage Browser
Rufen Sie BUCKET auf und gehen Sie zum WORK_DIR, das in der Datei nextflow.config angegeben ist.
Durchsuchen Sie die Unterordner und löschen Sie alle nicht benötigten Dateien oder Verzeichnisse. Wenn Sie alle Dateien löschen möchten, löschen Sie das gesamte WORK_DIR.

gcloud

Öffnen Sie Cloud Shell und führen Sie Folgendes aus:

Zu Cloud Shell
So entfernen Sie alle Zwischendateien aus dem Verzeichnis WORK_DIR:
```
gsutil -m rm gs://BUCKET/WORK_DIR/**
```

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das zum Ausführen der Anleitung erstellte Projekt löschen.

So löschen Sie das Projekt:

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

Alle Inhalte des Projekts werden gelöscht. Wenn Sie für diese Anleitung ein bereits bestehendes Projekt verwendet haben, 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 Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, wenn Sie Projekte wiederverwenden.

Wechseln Sie in der Cloud Console zur Seite Ressourcen verwalten.
Zur Seite „Ressourcen verwalten“
Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen.
Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.

Nächste Schritte

Ausführlichere Hintergrundinformationen, Dokumentationen und Unterstützung bezüglich Nextflow sind auf der Nextflow-Website, im Nextflow GitHub-Repository und in der Nextflow-Dokumentation verfügbar.