Exécuter Nextflow

Cette page explique comment exécuter un pipeline Nextflow sur Google Cloud.

Le pipeline utilisé dans ce tutoriel est une démonstration de faisabilité d'un pipeline RNA-Seq destiné à illustrer l'utilisation de Nextflow sur Google Cloud.

Objectifs

À la fin de ce tutoriel, vous maîtriserez les opérations suivantes :

  • Installer Nextflow dans Cloud Shell
  • Configurer un pipeline Nextflow
  • Exécuter un pipeline utilisant Nextflow sur Google Cloud

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

  • Compute Engine
  • Cloud Storage

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  4. Activer les API Cloud Life Sciences, Compute Engine, and Cloud Storage.

    Activer les API

    5.

  5. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  6. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  7. Activer les API Cloud Life Sciences, Compute Engine, and Cloud Storage.

    Activer les API

    8.

Créer un bucket Cloud Storage

Créez un bucket portant un nom unique en vous aidant des consignes de dénomination des buckets. Le bucket stocke les fichiers temporaires de travail et de sortie de ce tutoriel. Pour des raisons de compatibilité DNS, ce tutoriel ne fonctionne pas avec les noms de buckets contenant un trait de soulignement (_).

Console

  1. Dans la console Google Cloud, accédez à la page Navigateur de Cloud Storage:

    Accéder à la page du navigateur

  2. Cliquez sur Create bucket (Créer un bucket).

  3. Sur la page Créer un bucket, saisissez les informations concernant votre bucket.

  4. Cliquez sur Créer.

gsutil

  1. Ouvrez Cloud Shell.

    Accéder à Cloud Shell

  2. Exécutez la commande gsutil mb :

    gsutil mb gs://BUCKET_NAME

    Remplacez BUCKET_NAME par le nom que vous souhaitez attribuer à votre bucket, ce nom étant soumis à des exigences de dénomination. Exemple :my-bucket

    Si la requête aboutit, la commande renvoie le message suivant :

    Creating gs://BUCKET_NAME/...

Créer un compte de service et ajouter des rôles

Effectuez les étapes ci-dessous pour créer un compte de service et ajouter les rôles Identity and Access Management suivants :

  • Exécuteur de workflows Cloud Life Sciences
  • Utilisateur du compte de service
  • Consommateur Service Usage

  • Administrateur des objets de l'espace de stockage

Console

Créez un compte de service à l'aide de la console Google Cloud:

  1. Dans Google Cloud Console, accédez à la page Comptes de service.

    Accéder à la page "Comptes de service"

  2. Cliquez sur Créer un compte de service.

  3. Dans le champ Service account name (Nom du compte de service), saisissez nextflow-service-account et cliquez sur Create (Créer).

  4. Dans la section Grant this service account access to project (Autoriser ce compte de service à accéder au projet), ajoutez les rôles suivants dans la liste déroulante Select a role (Sélectionnez un rôle) :

    • Exécuteur de workflows Cloud Life Sciences
    • Utilisateur du compte de service
    • Consommateur Service Usage
    • Administrateur des objets de l'espace de stockage

  5. Cliquez sur Continue (Continuer), puis sur Done (OK).

  6. Sur la page Service Accounts (Comptes de service), recherchez le compte de service que vous avez créé. , puis cliquez surManage keys (Gérer les clés).

  7. Sur la page Keys (Clés), cliquez sur Add key (Ajouter une clé), puis sur Create new key (Créer une clé).

  8. Sélectionnez JSON pour le type de clé, puis cliquez sur Créer.

    Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.

gcloud

Effectuez la procédure suivante avec Cloud Shell :

  1. Ouvrez Cloud Shell.

    Accéder à Cloud Shell

  2. Définissez les variables à utiliser lors de la création du compte de service, en remplaçant PROJECT_ID par l'ID de votre projet.

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

  3. Créez le compte de service.

    gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

  4. Celui-ci a besoin des rôles IAM suivants :

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

    Attribuez ces rôles en exécutant les commandes suivantes dans Cloud Shell :

    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

Fournir des identifiants à votre application

Vous pouvez fournir des identifiants d'authentification au code ou aux commandes de votre application en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin du fichier JSON contenant votre clé de compte de service.

Les étapes suivantes montrent comment définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Console

  1. Ouvrez Cloud Shell.

    Accéder à Cloud Shell

  2. Dans le menu Plus  de Cloud Shell, choisissez Import file (Importer un fichier), puis sélectionnez le fichier de clé JSON que vous avez créé. Le fichier est importé dans le répertoire d'accueil de votre instance Cloud Shell.

  3. Vérifiez que le fichier importé se trouve dans votre répertoire actuel, puis confirmez son nom en exécutant la commande suivante :

    ls

  4. Définissez les identifiants en remplaçant KEY_FILENAME.json par le nom de votre fichier de clé. 

    export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY_FILENAME.json

gcloud

Effectuez la procédure suivante avec Cloud Shell :

  1. Ouvrez Cloud Shell.

    Accéder à Cloud Shell

  2. Dans le menu Plus  de Cloud Shell, choisissez Import file (Importer un fichier), puis sélectionnez le fichier de clé JSON que vous avez créé. Le fichier est importé dans le répertoire d'accueil de votre instance Cloud Shell.

  3. Vérifiez que le fichier importé se trouve dans votre répertoire actuel, puis confirmez son nom en exécutant la commande suivante :

    ls

  4. Définissez le fichier de clé privée sur la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS :

    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}

Installer et configurer Nextflow dans Cloud Shell

Pour éviter d'avoir à installer des logiciels sur votre ordinateur, continuez à exécuter toutes les commandes de terminal de ce tutoriel à partir de Cloud Shell.

  1. Si ce n'est pas déjà fait, ouvrez Cloud Shell.

    Accéder à Cloud Shell

  2. Installez Nextflow en exécutant les commandes suivantes :

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

    Si l'installation se termine correctement, le message suivant s'affiche :

        N E X T F L O W
version 21.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

  3. Exécutez la commande suivante pour cloner le dépôt de l'exemple de pipeline. Le dépôt inclut le pipeline à exécuter et les exemples de données qu'il utilise.

    git clone https://github.com/nextflow-io/rnaseq-nf.git

  4. Pour configurer Nextflow, procédez comme suit :

    1. Accédez au dossier rnaseq-nf. 

      cd rnaseq-nf
git checkout v2.0

    2. À l'aide de l'éditeur de texte de votre choix, modifiez le fichier nommé nextflow.config et apportez les modifications suivantes à la section intitulée gls :

      • Ajoutez la ligne google.project si elle n'est pas présente.
      • Remplacez PROJECT_ID par l'ID du projet.
      • Si vous le souhaitez, modifiez la valeur de google.location. Il doit s'agir de l'un des emplacements de l'API Cloud Life Sciences actuellement disponibles.
      • Si vous le souhaitez, modifiez la valeur de google.region qui spécifie la région dans laquelle les VM Compute Engine seront lancées. Consultez la page Régions et zones de Compute Engine disponibles.
      • Remplacez BUCKET par le nom du bucket créé précédemment.
      • Remplacez WORK_DIR par le nom d'un dossier à utiliser pour la journalisation et la sortie. Utilisez un nom de répertoire qui n'existe pas encore dans votre bucket.
      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. Revenez au dossier précédent : 

      cd ..

Exécuter le pipeline à l'aide de Nextflow

Exécutez le pipeline à l'aide de Nextflow. Une fois le pipeline démarré, il continue de s'exécuter en arrière-plan jusqu'à la fin. L'exécution du pipeline peut prendre jusqu'à 10 minutes.

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

Une fois l'exécution du pipeline terminée, le message suivant s'affiche :

N E X T F L O W  ~  version 21.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

Afficher le résultat du pipeline Nextflow

Une fois l'exécution du pipeline achevée, vous pouvez vérifier le résultat ainsi que les journaux, les erreurs, les commandes exécutées et les fichiers temporaires.

Le pipeline enregistre le fichier de sortie final results/qc_report.html dans le bucket Cloud Storage spécifié dans le fichier nextflow.config.

Pour vérifier les fichiers de sortie individuels de chaque tâche et fichiers intermédiaires, procédez comme suit :

Console

  1. Dans la console Cloud Storage, ouvrez la page du navigateur de Cloud Storage :

    Accéder au navigateur Cloud Storage

  2. Accédez au BUCKET et à l'élément WORK_DIR spécifié dans le fichier nextflow.config.

  3. Il existe un dossier pour chacune des tâches distinctes exécutées dans le pipeline.

  4. Le dossier contient les commandes exécutées, les fichiers de sortie et les fichiers temporaires utilisés au cours du processus.

gcloud

  1. Pour afficher les fichiers de sortie dans Cloud Shell, commencez par ouvrir Cloud Shell :

    Accéder à Cloud Shell

  2. Exécutez la commande suivante pour répertorier les résultats dans votre bucket Cloud Storage. Mettez à jour BUCKET et WORK_DIR vers les variables spécifiées dans le fichier nextflow.config.

    gsutil ls gs://BUCKET/WORK_DIR

  3. Le résultat affiche un dossier pour chacune des tâches exécutées. Pour afficher tous les fichiers créés par le pipeline, continuez à répertorier le contenu des sous-répertoires suivants. Mettez à jour TASK_FOLDER pour qu'il soit l'un des dossiers de tâches répertoriés dans la commande ci-dessus.

    gsutil ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER

Vous pouvez afficher les fichiers intermédiaires créés par le pipeline et sélectionner ceux que vous souhaitez conserver, ou les supprimer pour réduire les coûts associés à Cloud Storage. Pour supprimer les fichiers, consultez la section Supprimer des fichiers intermédiaires du bucket Cloud Storage ci-après.

Dépannage

  • Si vous rencontrez des problèmes lors de l'exécution du pipeline, consultez la page Dépannage de l'API Cloud Life Sciences.

  • Si votre pipeline échoue, vous pouvez vérifier les journaux de chaque tâche en consultant les fichiers journaux figurant dans chacun des dossiers de Cloud Storage, tels que .command.err, .command.log, .command.out, etc.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Une fois le tutoriel terminé, vous pouvez procéder au nettoyage des ressources que vous avez créées afin qu'elles ne soient plus comptabilisées dans votre quota et qu'elles ne vous soient plus facturées. Dans les sections suivantes, nous allons voir comment supprimer ou désactiver ces ressources.

Supprimer les fichiers intermédiaires du bucket Cloud Storage

Lorsque vous exécutez le pipeline, celui-ci stocke les fichiers intermédiaires dans gs://BUCKET/WORK_DIR. Vous pouvez supprimer les fichiers une fois le flux de travail terminé afin de réduire les frais générés par Cloud Storage.

Pour afficher la quantité d'espace utilisée dans le répertoire, exécutez la commande suivante :

gsutil du -sh gs://BUCKET/WORK_DIR

Pour supprimer des fichiers de WORK_DIR, procédez comme suit :

Console

  1. Dans la console Cloud Storage, ouvrez la page du navigateur de Cloud Storage :

    Accéder au navigateur Cloud Storage

  2. Accédez au BUCKET et à l'élément WORK_DIR spécifié dans le fichier nextflow.config.

  3. Parcourez les sous-dossiers et supprimez les fichiers ou répertoires que vous ne souhaitez pas conserver. Pour supprimer tous les fichiers, supprimez tout le répertoire WORK_DIR.

gcloud

  1. Ouvrez Cloud Shell et exécutez la commande suivante :

    Accéder à Cloud Shell

  2. Pour supprimer les fichiers intermédiaires du répertoire WORK_DIR, exécutez la commande suivante :

    gsutil -m rm gs://BUCKET/WORK_DIR/**

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  1. Dans la console Google Cloud, accédez à la page Gérer les ressources.

    Accéder à la page Gérer les ressources

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étapes suivantes

Les pages suivantes fournissent des informations de contexte, une documentation et une assistance pour l'utilisation de Nextflow :