Orchestrare i job eseguendo le pipeline Nextflow su Batch

Questo tutorial spiega come eseguire una pipeline Nextflow su Batch. Nello specifico, questo tutorial esegue la pipeline di esempio rnaseq-nf per le scienze biologiche di Nextflow, che quantifica le caratteristiche genomiche dai dati di lettura brevi utilizzando RNA-Seq.

Questo tutorial è destinato agli utenti di Batch che vogliono utilizzare Nextflow con Batch.

Nextflow è un software open source per l'orchestrazione di flussi di lavoro bioinformatici.

Nota: questo tutorial fornisce istruzioni per l'utilizzo di questa app: Nextflow versione 23.04.1. Le istruzioni potrebbero non rappresentare le versioni più recenti dell'app. Per ulteriori informazioni, consulta la documentazione: Nextflow.

Obiettivi

Completando questo tutorial, imparerai a:

• Installa Nextflow in Cloud Shell.
• Creare un bucket Cloud Storage.
• Configura una pipeline Nextflow.
• Esegui una pipeline di esempio utilizzando Nextflow su Batch.
• Visualizza gli output della pipeline.
• Libera spazio per evitare addebiti aggiuntivi in uno dei seguenti modi:
  • Elimina un progetto.
  • Elimina singole risorse.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Batch
• Cloud Storage

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Le risorse create in questo tutorial in genere costano meno di un dollaro, se completi tutti i passaggi, inclusa la pulizia, in modo tempestivo.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Abilita le API Batch, Cloud Storage, Compute Engine e Logging:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

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

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Abilita le API Batch, Cloud Storage, Compute Engine e Logging:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

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

1. Assicurati che il tuo progetto abbia una rete virtual private cloud (VPC) con una configurazione di rete valida per questo tutorial.

   Nota:non è richiesta alcuna azione per questo passaggio, a meno che la tua organizzazione non disattivi la creazione di reti default attivando il vincolo di criterio compute.skipDefaultNetworkCreation o il tuo progetto non abbia modificato la rete default.

   Questo tutorial presuppone che tu stia utilizzando la rete default. Per impostazione predefinita,le risorse Google Cloud utilizzano la rete default, che fornisce l'accesso alla rete necessario per questo tutorial.

   Obiettivo:se vuoi che un job Batch per una pipeline Nextflow utilizzi una rete diversa, puoi modificare il file nextflow.config in questo tutorial per definire anche la rete e la subnet del job utilizzando i campi google.batch.network e google.batch.subnetwork di Nextflow, rispettivamente. Tuttavia, devi anche assicurarti che la rete e la subnet siano configurate correttamente per il tuo workload. Per saperne di più, consulta Panoramica del networking batch.

2. Assicurati che il tuo progetto abbia almeno un service account con le autorizzazioni richieste per l'esecuzione del job batch in questo tutorial.

   Per impostazione predefinita, i job utilizzano il service account predefinito di Compute Engine, a cui viene concesso automaticamente il ruolo IAM Editor (roles/editor) e che dispone già di tutte le autorizzazioni richieste per questo tutorial.

   Nota: non è richiesta alcuna azione per questo passaggio, a meno che la tua organizzazione non disabiliti le autorizzazioni automatiche per i service account predefiniti attivando il vincolo di policy iam.automaticIamGrantsForDefaultServiceAccounts, il tuo progetto non abbia modificato il account di servizio predefinito di Compute Engine o tu non voglia utilizzare un account di servizio diverso.

   Per assicurarti che il account di servizio del job disponga delle autorizzazioni necessarie per consentire all'agente di servizio Batch di creare e accedere alle risorse per i job Batch, chiedi all'amministratore di concedere i seguenti ruoli IAMaccount di servizioount del job:

   Importante: devi concedere questi ruoli al account di servizio del job, non al tuo account utente. La mancata concessione dei ruoli all'entità corretta potrebbe comportare errori di autorizzazione.
   • Batch Agent Reporter (roles/batch.agentReporter) sul progetto
   • Storage Admin (roles/storage.admin) sul progetto
   • (Consigliato) Consenti ai job di generare log in Cloud Logging: Scrittore log (roles/logging.logWriter) sul progetto

   Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

   L'amministratore potrebbe anche assegnare al account di servizio del job le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

3. Assicurati di disporre delle autorizzazioni necessarie per questo tutorial.

   Nota:se hai creato il progetto che intendi utilizzare per questo tutorial, non è richiesta alcuna azione per questo passaggio. In qualità di creatore del progetto, ti viene concesso automaticamente il ruolo IAM Proprietario (roles/owner), che dispone già di tutte le autorizzazioni richieste per questo tutorial.

   Per ottenere le autorizzazioni necessarie per completare questo tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM:

   • Batch Job Editor (roles/batch.jobsEditor) sul progetto
   • Service Account User (roles/iam.serviceAccountUser) sul account di servizio del job
   • Storage Object Admin (roles/storage.objectAdmin) sul progetto

4. Installa Nextflow:

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

   L'output dovrebbe essere simile al seguente:

   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
   

Crea un bucket Cloud Storage

Per creare un bucket Cloud Storage in cui archiviare i file di lavoro e di output temporanei della pipeline Nextflow, utilizza la console o la riga di comando. Google Cloud

Console

Per creare un bucket Cloud Storage utilizzando la console Google Cloud , segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Bucket.

   Vai a Bucket

2. Fai clic su Crea.

3. Nella pagina Crea un bucket, inserisci un nome univoco globale per il bucket.

4. Fai clic su Crea.

5. Nella finestra L'accesso pubblico verrà vietato, fai clic su Conferma.

gcloud

Per creare un bucket Cloud Storage utilizzando Google Cloud CLI, utilizza il comando gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Sostituisci BUCKET_NAME con un nome globalmente univoco per il bucket.

Se la richiesta ha esito positivo, l'output dovrebbe essere simile al seguente:

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

Configura Nextflow

Per configurare la pipeline Nextflow in modo che venga eseguita su Batch, segui questi passaggi nella riga di comando:

1. Clona il repository della pipeline di esempio:

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

2. Vai alla cartella rnaseq-nf:

   cd rnaseq-nf
   

3. Apri il file nextflow.config:

   nano nextflow.config
   

   Il file deve contenere la seguente sezione google-batch:

   '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. Nella sezione google-batch, segui questi passaggi:

   1. Sostituisci BUCKET_NAME con il nome del bucket Cloud Storage che hai creato nei passaggi precedenti.

   2. Sostituisci WORK_DIRECTORY con il nome di una nuova cartella che la pipeline può utilizzare per archiviare log e output.

      Ad esempio, inserisci workDir.

   3. Sostituisci REGION con la regione da utilizzare.

      Ad esempio, inserisci us-central1.

   4. Dopo il campo google.region, aggiungi i seguenti campi:

      1. Aggiungi il campo google.project:

         google.project = 'PROJECT_ID'
         

         Sostituisci PROJECT_ID con l'ID progetto del progetto Google Cloud corrente.

      2. Se non utilizzi il account di servizio predefinito di Compute Engine comeaccount di serviziot del job, aggiungi il campo google.batch.serviceAccountEmail:

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         Sostituisci SERVICE_ACCOUNT_EMAIL con l'indirizzo email del account di servizio del job che hai preparato per questo tutorial.

      Obiettivo: per scoprire tutti i campi che puoi specificare per configurare il job Batch per una pipeline Nextflow, consulta la documentazione di Nextflow per l'ambito di configurazione Batch.

5. Per salvare le modifiche:

   1. Premi Control+S.

   2. Inserisci Y.

   3. Premi Enter.

esegui la pipeline.

Esegui la pipeline Nextflow di esempio utilizzando la riga di comando:

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

La pipeline esegue un piccolo set di dati utilizzando le impostazioni fornite nei passaggi precedenti. Il completamento di questa operazione potrebbe richiedere fino a 10 minuti.

Al termine dell'esecuzione della pipeline, l'output dovrebbe essere simile al seguente:

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

Visualizza gli output della pipeline

Al termine dell'esecuzione, la pipeline archivia i file di output, i log, gli errori o i file temporanei nel file results/qc_report.html all'interno della cartella WORK_DIRECTORY del bucket Cloud Storage.

Per controllare i file di output della pipeline nella cartella WORK_DIRECTORY del bucket Cloud Storage, puoi utilizzare la console Google Cloud o la riga di comando.

Console

Per controllare i file di output della pipeline utilizzando la console Google Cloud , segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Bucket.

   Vai a Bucket

2. Nella colonna Nome, fai clic sul nome del bucket creato nei passaggi precedenti.

3. Nella pagina Dettagli bucket, apri la cartella WORK_DIRECTORY.

Esiste una cartella per ogni attività separata eseguita dal flusso di lavoro. Ogni cartella contiene i comandi eseguiti, i file di output e i file temporanei creati dalla pipeline.

gcloud

Per controllare i file di output della pipeline utilizzando gcloud CLI, utilizza il comando gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket creato nei passaggi precedenti.

• WORK_DIRECTORY: la directory specificata nel file nextflow.config.

L'output elenca una cartella per ogni attività separata eseguita dalla pipeline. Ogni cartella contiene i comandi eseguiti, i file di output e i file temporanei creati dalla pipeline.

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto corrente.

Per eliminare il progetto corrente, utilizza la console Google Cloud o gcloud CLI.

Console

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud , vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona quello che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

gcloud

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Elimina un progetto Google Cloud :

gcloud projects delete PROJECT_ID

Elimina singole risorse

Se vuoi continuare a utilizzare il progetto attuale, elimina le singole risorse utilizzate in questo tutorial.

Elimina il bucket

Se non hai più bisogno del bucket che hai utilizzato in questo tutorial, eliminalo.

Elimina i file di output nel bucket

Al termine dell'esecuzione della pipeline, vengono creati e archiviati i file di output nella cartella WORK_DIRECTORY del bucket Cloud Storage.

Per ridurre i costi di Cloud Storage all'account Google Cloud corrente, puoi eliminare la cartella contenente i file di output della pipeline utilizzando la console Google Cloud o la riga di comando.

Console

Per eliminare la cartella WORK_DIRECTORY e tutti i file di output dal bucket Cloud Storage utilizzando la consoleGoogle Cloud , segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Bucket.

   Vai a Bucket

2. Nella colonna Nome, fai clic sul nome del bucket creato nei passaggi precedenti.

3. Nella pagina Dettagli bucket, seleziona la riga contenente la cartella WORK_DIRECTORY, quindi procedi come segue:

   1. Fai clic su Elimina.

   2. Per confermare, inserisci DELETE e fai clic su Elimina.

gcloud

Per eliminare la cartella WORK_DIRECTORY e tutti i file di output dal bucket Cloud Storage utilizzando gcloud CLI, utilizza il comando gcloud storage rm con il flag --recursive.

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

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket specificato nei passaggi precedenti.

• WORK_DIRECTORY: la directory in cui archiviare i file di output della pipeline specificati nei passaggi precedenti.

Passaggi successivi

• Per saperne di più sul deployment dei flussi di lavoro Nextflow, consulta il repository GitHub di Nextflow.

• Per saperne di più sui processi, sugli script e sulle opzioni di configurazione di Nextflow, consulta la documentazione di Nextflow.