Orchestrate jobs by running Nextflow pipelines on Batch

Ce tutoriel explique comment exécuter un pipeline Nextflow sur Batch. Plus précisément, ce tutoriel exécute l'exemple de pipeline rnaseq-nf Life Sciences de Nextflow, qui quantifie les caractéristiques génomiques à partir de données de lecture courte à l'aide de RNA-Seq.

Ce tutoriel s'adresse aux utilisateurs de Batch qui souhaitent utiliser Nextflow avec Batch.

Nextflow est un logiciel Open Source permettant d'orchestrer des workflows de bio-informatique.

Remarque : Ce tutoriel fournit des instructions d'utilisation pour l'application Nextflow version 23.04.1. Ces instructions peuvent ne pas représenter les versions les plus récentes de l'application. Pour en savoir plus, consultez la documentation : Nextflow.

Objectifs

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

• Installez Nextflow dans Cloud Shell.
• créer un bucket Cloud Storage ;
• Configurer un pipeline Nextflow
• Exécuter un exemple de pipeline à l'aide de Nextflow sur Batch
• Affichez les sorties du pipeline.
• Pour éviter que des frais supplémentaires ne vous soient facturés, effectuez l'une des opérations suivantes :
  • Supprimez un projet.
  • Supprimez les ressources individuelles.

Coûts

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

• Batch
• Cloud Storage

Pour obtenir une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Les ressources créées dans ce tutoriel coûtent généralement moins d'un dollar, en supposant que vous effectuiez toutes les étapes, y compris le nettoyage, en temps opportun.

Avant de commencer

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 sans frais pour exécuter, tester et déployer des charges de travail.

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

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

Activez les API Batch, Cloud Storage, Compute Engine et Logging :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

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

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

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

Activez les API Batch, Cloud Storage, Compute Engine et Logging :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

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

1. Assurez-vous que votre projet dispose d'un réseau de cloud privé virtuel (VPC) avec une configuration réseau valide pour ce tutoriel.

   Remarque : Aucune action n'est requise pour cette étape, sauf si votre organisation désactive la création de réseaux default en activant la contrainte de règle compute.skipDefaultNetworkCreation ou si votre projet a modifié son réseau default.

   Ce tutoriel suppose que vous utilisez le réseau default. Par défaut,les ressources Google Cloud utilisent le réseau default, qui fournit l'accès au réseau requis pour ce tutoriel.

   Objectif : si vous souhaitez qu'un job Batch pour un pipeline Nextflow utilise un autre réseau, vous pouvez modifier le fichier nextflow.config de ce tutoriel pour définir également le réseau et le sous-réseau du job à l'aide des champs Nextflow google.batch.network et google.batch.subnetwork, respectivement. Toutefois, vous devez également vous assurer que le réseau et le sous-réseau sont correctement configurés pour votre charge de travail. Pour en savoir plus, consultez Présentation de la mise en réseau par lot.

2. Assurez-vous que votre projet dispose d'au moins un compte de service avec les autorisations requises pour exécuter le job Batch dans ce tutoriel.

   Par défaut, les jobs utilisent le compte de service Compute Engine par défaut, qui se voit automatiquement attribuer le rôle IAM Éditeur (roles/editor) et dispose déjà de toutes les autorisations requises pour ce tutoriel.

   Remarque : Aucune action n'est requise pour cette étape, sauf si votre organisation désactive les autorisations automatiques pour les comptes de service par défaut en activant la contrainte de règle iam.automaticIamGrantsForDefaultServiceAccounts, si votre projet a modifié son compte de service Compute Engine par défaut ou si vous souhaitez utiliser un autre compte de service.

   Pour vous assurer que le compte de service du job dispose des autorisations nécessaires pour permettre à l'agent de service Batch de créer des ressources pour les jobs Batch et d'y accéder, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service du job :

   Important : Vous devez accorder ces rôles au compte de service du job, et non à votre compte utilisateur. Si vous ne les accordez pas au bon compte principal, vous risquez de rencontrer des erreurs d'autorisation.
   • Responsable du signalement d'agent par lot (roles/batch.agentReporter) sur le projet
   • Administrateur de l'espace de stockage (roles/storage.admin) sur le projet
   • (Recommandé) Autorisez les jobs à générer des journaux dans Cloud Logging : Rédacteur de journaux (roles/logging.logWriter) sur le projet

   Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

   Votre administrateur peut également attribuer au compte de service du job les autorisations requises à l'aide de rôles personnalisés ou d'autres rôles prédéfinis.

3. Assurez-vous de disposer des autorisations requises pour ce tutoriel.

   Remarque : Si vous avez créé le projet que vous prévoyez d'utiliser pour ce tutoriel, aucune action n'est requise pour cette étape. En tant que créateur du projet, vous disposez automatiquement du rôle IAM Propriétaire (roles/owner), qui inclut déjà toutes les autorisations requises pour ce tutoriel.

   Pour obtenir les autorisations nécessaires pour suivre ce tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants :

   • Éditeur de tâches par lot (roles/batch.jobsEditor) sur le projet
   • Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le compte de service du job
   • Administrateur des objets Storage (roles/storage.objectAdmin) sur le projet

4. Installez Nextflow :

   curl -s -L https://github.com/nextflow-io/nextflow/releases/download/v23.04.1/nextflow | bash
   

   La sortie devrait ressembler à ce qui suit :

   N E X T F L O W
   version 23.04.1 build 5866
   created 15-04-2023 06:51 UTC
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   - the executable file `nextflow` has been created in the folder: ...
   - you may complete the installation by moving it to a directory in your $PATH
   

Créer un bucket Cloud Storage

Pour créer un bucket Cloud Storage afin de stocker les fichiers de travail et de sortie temporaires du pipeline Nextflow, utilisez la console Google Cloud ou la ligne de commande.

Console

Pour créer un bucket Cloud Storage à l'aide de la console Google Cloud , procédez comme suit :

1. Dans la console Google Cloud , accédez à la page Buckets.

   Accéder à la page "Buckets"

2. Cliquez sur Créer.

3. Sur la page Créer un bucket, saisissez un nom unique pour votre bucket.

4. Cliquez sur Créer.

5. Dans la fenêtre L'accès public sera bloqué, cliquez sur Confirmer.

gcloud

Pour créer un bucket Cloud Storage à l'aide de la Google Cloud CLI, utilisez la commande gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Remplacez BUCKET_NAME par un nom unique pour votre bucket.

Si la requête aboutit, le résultat doit ressembler à ce qui suit :

Creating gs://BUCKET_NAME/...
   ```

Configurer Nextflow

Pour configurer le pipeline Nextflow afin qu'il s'exécute sur Batch, procédez comme suit dans la ligne de commande :

1. Clonez l'exemple de dépôt de pipeline :

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

2. Accédez au dossier rnaseq-nf :

   cd rnaseq-nf
   

3. Ouvrez le fichier nextflow.config :

   nano nextflow.config
   

   Le fichier doit contenir la section google-batch suivante :

   'google-batch' {
       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-batch'
       process.container = 'docker.io/nextflow/rnaseq-nf:v1.3.1'
       /*
        * replace with your own bucket!
        */
       workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
       google.region  = 'REGION'
   }
   

4. Dans la section google-batch, procédez comme suit :

   1. Remplacez BUCKET_NAME par le nom du bucket Cloud Storage que vous avez créé lors des étapes précédentes.

   2. Remplacez WORK_DIRECTORY par le nom d'un nouveau dossier que le pipeline peut utiliser pour stocker les journaux et les sorties.

      Par exemple, saisissez workDir.

   3. Remplacez REGION par la région à utiliser.

      Par exemple, saisissez us-central1.

   4. Après le champ google.region, ajoutez les champs suivants :

      1. Ajoutez le champ google.project :

         google.project = 'PROJECT_ID'
         

         Remplacez PROJECT_ID par l'ID du projet Google Cloud actuel.

      2. Si vous n'utilisez pas le compte de service Compute Engine par défaut comme compte de service du job, ajoutez le champ google.batch.serviceAccountEmail :

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         Remplacez SERVICE_ACCOUNT_EMAIL par l'adresse e-mail du compte de service du job que vous avez préparé pour ce tutoriel.

      Objectif : Pour en savoir plus sur tous les champs que vous pouvez spécifier pour configurer le job Batch d'un pipeline Nextflow, consultez la documentation Nextflow sur le champ d'application de la configuration Batch.

5. Pour enregistrer vos modifications :

   1. Appuyez sur la touche Control+S.

   2. Saisissez Y.

   3. Appuyez sur la touche Enter.

Exécuter le pipeline

Exécutez l'exemple de pipeline Nextflow à l'aide de la ligne de commande :

../nextflow run nextflow-io/rnaseq-nf -profile google-batch

Le pipeline exécute un petit ensemble de données à l'aide des paramètres que vous avez fournis lors des étapes précédentes. Cette opération peut prendre jusqu'à 10 minutes.

Une fois le pipeline exécuté, le résultat devrait ressembler à ce qui suit :

N E X T F L O W  ~  version 23.04.1
Launching `https://github.com/nextflow-io/rnaseq-nf` [crazy_curry] DSL2 - revision: 88b8ef803a [master]
 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

Uploading local `bin` scripts folder to gs://example-bucket/workdir/tmp/53/2847f2b832456a88a8e4cd44eec00a/bin
executor >  google-batch (4)
[67/71b856] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[0c/2c79c6] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[a9/571723] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/1f0dd4] process > MULTIQC                       [100%] 1 of 1 ✔

Done! Open the following report in your browser --> results/multiqc_report.html

Completed at: 20-Apr-2023 15:44:55
Duration    : 10m 13s
CPU hours   : (a few seconds)
Succeeded   : 4

Afficher les sorties du pipeline

Une fois le pipeline exécuté, il stocke les fichiers de sortie, les journaux, les erreurs ou les fichiers temporaires dans le fichier results/qc_report.html du dossier WORK_DIRECTORY de votre bucket Cloud Storage.

Pour vérifier les fichiers de sortie du pipeline dans le dossier WORK_DIRECTORY de votre bucket Cloud Storage, vous pouvez utiliser la console Google Cloud ou la ligne de commande.

Console

Pour vérifier les fichiers de sortie du pipeline à l'aide de la console Google Cloud , procédez comme suit :

1. Dans la console Google Cloud , accédez à la page Buckets.

   Accéder à la page "Buckets"

2. Dans la colonne Nom, cliquez sur le nom du bucket que vous avez créé lors des étapes précédentes.

3. Sur la page Informations sur le bucket, ouvrez le dossier WORK_DIRECTORY.

Il existe un dossier pour chacune des tâches distinctes exécutées par le workflow. Chaque dossier contient les commandes exécutées, les fichiers de sortie et les fichiers temporaires créés par le pipeline.

gcloud

Pour vérifier les fichiers de sortie du pipeline à l'aide de gcloud CLI, utilisez la commande gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Remplacez les éléments suivants :

• BUCKET_NAME : nom du bucket que vous avez créé lors des étapes précédentes.

• WORK_DIRECTORY : répertoire que vous avez spécifié dans le fichier nextflow.config.

Le résultat liste un dossier pour chacune des tâches distinctes exécutées par le pipeline. Chaque dossier contient les commandes exécutées, les fichiers de sortie et les fichiers temporaires créés par le pipeline.

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.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet actuel.

Pour supprimer le projet actuel, utilisez la console Google Cloud ou la gcloud CLI.

Console

Attention : La suppression d'un projet aura les effets suivants :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

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.

gcloud

Attention : La suppression d'un projet aura les effets suivants :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Supprimer un projet Google Cloud  :

gcloud projects delete PROJECT_ID

Supprimer des ressources individuelles

Si vous souhaitez continuer à utiliser le projet actuel, supprimez les ressources individuelles utilisées dans ce tutoriel.

Supprimer le bucket

Si vous n'avez plus besoin du bucket que vous avez utilisé dans ce tutoriel, supprimez-le.

Supprimez les fichiers de sortie du bucket.

Une fois le pipeline exécuté, il crée et stocke des fichiers de sortie dans le dossier WORK_DIRECTORY de votre bucket Cloud Storage.

Pour réduire les frais Cloud Storage facturés sur le compteGoogle Cloud actuel, vous pouvez supprimer le dossier contenant les fichiers de sortie du pipeline à l'aide de la console Google Cloud ou de la ligne de commande.

Console

Pour supprimer le dossier WORK_DIRECTORY et tous les fichiers de sortie de votre bucket Cloud Storage à l'aide de la consoleGoogle Cloud , procédez comme suit :

1. Dans la console Google Cloud , accédez à la page Buckets.

   Accéder à la page "Buckets"

2. Dans la colonne Nom, cliquez sur le nom du bucket que vous avez créé lors des étapes précédentes.

3. Sur la page Informations sur le bucket, sélectionnez la ligne contenant le dossier WORK_DIRECTORY, puis procédez comme suit :

   1. Cliquez sur Supprimer.

   2. Pour confirmer, saisissez DELETE, puis cliquez sur Supprimer.

gcloud

Pour supprimer le dossier WORK_DIRECTORY et tous les fichiers de sortie de votre bucket Cloud Storage à l'aide de la gcloud CLI, utilisez la commande gcloud storage rm avec le flag --recursive.

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

Remplacez les éléments suivants :

• BUCKET_NAME : nom du bucket que vous avez spécifié aux étapes précédentes.

• WORK_DIRECTORY : répertoire dans lequel stocker les fichiers de sortie du pipeline que vous avez spécifiés aux étapes précédentes.

Étapes suivantes

• Pour en savoir plus sur le déploiement des workflows Nextflow, consultez le dépôt GitHub Nextflow.

• Pour en savoir plus sur les processus, les scripts et les options de configuration Nextflow, consultez la documentation Nextflow.