Batch で Nextflow パイプラインを実行してジョブをオーケストレート

このチュートリアルでは、Batch で Nextflow パイプラインを実行する方法について説明します。具体的には、このチュートリアルでは　RNA-Seq を使用して短いリードデータからゲノムの特徴を定量化する Nextflow のサンプル rnaseq-nf ライフ サイエンス パイプラインを実行します。

このチュートリアルは、Batch で Nextflow を使用する Batch ユーザーを対象としています。

Nextflow は、バイオインフォマティクス ワークフローをオーケストレートするためのオープンソース ソフトウェアです。

注: このチュートリアルで操作手順を説明する対象のアプリは、 Nextflowversion 23.04.1です。ここで説明している手順は、新しいバージョンのアプリ用でない場合があります。詳細については、ドキュメント（Nextflow）をご覧ください。

目標

このチュートリアルを完了すると、次のことができるようになります。

• Cloud Shell に Nextflow をインストールします。
• Cloud Storage バケットを作成する。
• Nextflow パイプラインを構成する。
• Batch で Nextflow を使用してサンプル パイプラインを実行する。
• パイプラインの出力を表示します。
• 次のいずれかを行って、追加料金が発生しないようにクリーンアップします。
  • プロジェクトを削除する。
  • リソースを個別に削除する。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

• Batch
• Cloud Storage

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このチュートリアルで作成されるリソースにかかる費用は、クリーンアップを含むすべての手順を適切なタイミングで完了した場合、通常 1 ドル未満です。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

1. このチュートリアルで使用する有効なネットワーキング構成を持つ Virtual Private Cloud（VPC）ネットワークがプロジェクトにあることを確認します。

   注: 組織で compute.skipDefaultNetworkCreation ポリシーの制約を有効にして default ネットワークの作成を無効にしている場合や、プロジェクトで default ネットワークを変更している場合を除き、この手順で必要な操作はありません。

   このチュートリアルでは、default ネットワークを使用していることを前提としています。デフォルトでは、 Google Cloud リソースは default ネットワークを使用します。このネットワークは、このチュートリアルで必要なネットワーク アクセスを提供します。

   目的: 必要に応じて、Nextflow パイプラインの Batch ジョブで別のネットワークを使用する場合は、このチュートリアルの nextflow.config ファイルを変更して、Nextflow フィールド google.batch.network と google.batch.subnetwork を使用して、ジョブのネットワークとサブネットを定義することもできます。ただし、ワークロード用にネットワークとサブネットが正しく構成されていることも確認する必要があります。詳細については、Batch ネットワーキングの概要をご覧ください。

2. このチュートリアルの Batch ジョブの実行に必要な権限を持つサービス アカウントがプロジェクトに 1 つ以上存在することを確認します。

   デフォルトでは、ジョブは Compute Engine のデフォルトのサービス アカウントを使用します。このアカウントには編集者（roles/editor）の IAM ロールが自動的に付与され、このチュートリアルに必要なすべての権限がすでに含まれています。

   注: 組織で iam.automaticIamGrantsForDefaultServiceAccounts ポリシーの制約を有効にしてデフォルトのサービス アカウントに対する権限の自動付与を無効にしている場合、プロジェクトで Compute Engine のデフォルトのサービス アカウントが変更されている場合、または別のサービス アカウントを使用する場合を除き、この手順で必要な操作はありません。

   ジョブのサービス アカウントに Batch サービス エージェントが Batch ジョブのリソースを作成およびアクセスするために必要な権限を付与するには、ジョブのサービス アカウントに次の IAM ロールを付与するように管理者に依頼してください。

   重要: これらのロールは、ユーザー アカウントではなく、ジョブのサービス アカウントに付与する必要があります。正しいプリンシパルにロールを付与しないと、権限エラーが発生する可能性があります。
   • プロジェクトに対するバッチ エージェント報告者 （roles/batch.agentReporter）
   • プロジェクトに対する Storage 管理者 （roles/storage.admin）
   • （推奨）ジョブで Cloud Logging のログを生成できるようにする: プロジェクトに対するログ書き込み （roles/logging.logWriter）

   ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

   管理者は、カスタムロールや他の事前定義ロールを使用して、必要な権限をジョブのサービス アカウントに付与することもできます。

3. このチュートリアルで必要な権限があることを確認します。

   注: このチュートリアルで使用する予定のプロジェクトを作成した場合、この手順で必要な操作はありません。プロジェクト作成者にはオーナー（roles/owner）の IAM ロールが自動的に付与されます。このロールには、このチュートリアルに必要なすべての権限がすでに含まれています。

   このチュートリアルを完了するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

   • プロジェクトに対する Batch ジョブ編集者 （roles/batch.jobsEditor）
   • ジョブのサービス アカウントに対するサービス アカウント ユーザー （roles/iam.serviceAccountUser）
   • プロジェクトに対する Storage オブジェクト管理者 （roles/storage.objectAdmin）

4. Nextflow をインストールします。

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

   出力例を以下に示します。

   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
   

Cloud Storage バケットを作成する

Nextflow パイプラインの一時ファイルと出力ファイルを保存する Cloud Storage バケットを作成するには、 Google Cloud コンソールまたはコマンドラインを使用します。

コンソール

Google Cloud コンソールを使用して Cloud Storage バケットを作成する手順は次のとおりです。

1. Google Cloud コンソールで [バケット] ページに移動します。

   [バケット] に移動

2. [ 作成] をクリックします。

3. [バケットの作成] ページで、バケットのグローバルに一意の名前を入力します。

4. [作成] をクリックします。

5. [公開アクセスの防止] ウィンドウで [確認] をクリックします。

gcloud

Google Cloud CLI を使用して Cloud Storage バケットを作成するには、gcloud storage buckets create コマンドを使用します。

gcloud storage buckets create gs://BUCKET_NAME

BUCKET_NAME は、バケットのグローバルに一意の名前に置き換えます。

リクエストが成功した場合、出力は次のようになります。

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

Nextflow を構成する

Batch で実行するように Nextflow パイプラインを構成するには、コマンドラインで次の手順を行います。

1. サンプル パイプライン リポジトリのクローンを作成します。

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

2. rnaseq-nf フォルダに移動します。

   cd rnaseq-nf
   

3. nextflow.config ファイルを開きます。

   nano nextflow.config
   

   このファイルには、次の gcb セクションが含まれている必要があります。

   gcb {
     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 = 'quay.io/nextflow/rnaseq-nf:v1.1'
     workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
     google.region  = 'REGION'
   }
   

4. [gcb] セクションで、次の操作を行います。

   1. BUCKET_NAME は、前の手順で作成した Cloud Storage バケットの名前に置き換えます。

   2. WORK_DIRECTORY は、パイプラインがログと出力を保存するために使用できる新しいフォルダの名前に置き換えます。

      たとえば、「workDir」と入力します。

   3. REGION は、使用するリージョンに置き換えます。

      たとえば、「us-central1」と入力します。

   4. google.region フィールドの後に、次のフィールドを追加します。

      1. google.project フィールドを追加します。

         google.project = 'PROJECT_ID'
         

         PROJECT_ID は、現在の Google Cloud プロジェクトのプロジェクト ID に置き換えます。

      2. Compute Engine のデフォルトのサービス アカウントをジョブのサービス アカウントとして使用していない場合は、google.batch.serviceAccountEmail フィールドを追加します。

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         SERVICE_ACCOUNT_EMAIL は、このチュートリアル用に準備したジョブのサービス アカウントのメールアドレスに置き換えます。

      目的: Nextflow パイプラインの Batch ジョブを構成するために指定できるすべてのフィールドについては、Batch 構成スコープに関する Nextflow のドキュメントをご覧ください。

5. 編集内容を保存する手順は次のとおりです。

   1. Control+S キーを押します。

   2. 「Y」と入力します。

   3. Enter キーを押します。

パイプラインを実行する

コマンドラインを使用して、サンプル Nextflow パイプラインを実行します。

../nextflow run nextflow-io/rnaseq-nf -profile gcb

パイプラインは、前の手順で指定した設定を使用して小さなデータセットを実行します。このオペレーションが完了するまでに 10 分ほどかかることがあります。

パイプラインの実行が完了すると、出力は次のようになります。

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

パイプラインの出力を表示する

パイプラインの実行が完了すると、出力ファイル、ログ、エラー、一時ファイルが Cloud Storage バケットの WORK_DIRECTORY フォルダ内の results/qc_report.html ファイルに保存されます。

Cloud Storage バケットの WORK_DIRECTORY フォルダにあるパイプラインの出力ファイルを確認するには、 Google Cloud コンソールまたはコマンドラインを使用します。

コンソール

Google Cloud コンソールを使用してパイプラインの出力ファイルを確認する手順は次のとおりです。

1. Google Cloud コンソールで [バケット] ページに移動します。

   [バケット] に移動

2. [名前] 列で、前の手順で作成したバケットの名前をクリックします。

3. [バケットの詳細] ページで、WORK_DIRECTORY フォルダを開きます。

ワークフローで実行したタスクごとにフォルダがあります。各フォルダには、実行されたコマンド、出力ファイル、パイプラインによって作成された一時ファイルが格納されます。

gcloud

gcloud CLI を使用してパイプラインの出力ファイルを確認するには、gcloud storage ls コマンドを使用します。

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

以下を置き換えます。

• BUCKET_NAME: 前の手順で作成したバケットの名前。

• WORK_DIRECTORY: nextflow.config ファイルで指定したディレクトリ。

出力には、パイプラインで実行されたタスクごとにフォルダが表示されます。各フォルダには、実行されたコマンド、出力ファイル、パイプラインによって作成された一時ファイルが格納されます。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトの削除

課金をなくす最も簡単な方法は、現在のプロジェクトを削除することです。

現在のプロジェクトを削除するには、 Google Cloud コンソールまたは gcloud CLI を使用します。

コンソール

注意: プロジェクトを削除すると、次のような影響があります。

• プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにできます。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

gcloud

注意: プロジェクトを削除すると、次のような影響があります。

• プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

リソースを個別に削除する

現在のプロジェクトを引き続き使用する場合は、このチュートリアルで使用したリソースを個別に削除します。

バケットの削除

このチュートリアルで使用したバケットが不要になった場合は、バケットを削除します。

バケット内の出力ファイルを削除する

パイプラインの実行が完了すると、出力ファイルが作成されて Cloud Storage バケットの WORK_DIRECTORY フォルダに保存されます。

Cloud Storage の料金を現在のGoogle Cloud アカウントに減らすには、 Google Cloud コンソールまたはコマンドラインを使用して、パイプラインの出力ファイルを含むフォルダを削除します。

コンソール

Google Cloud コンソールを使用して Cloud Storage バケットから WORK_DIRECTORY フォルダとすべての出力ファイルを削除するには、次の操作を行います。

1. Google Cloud コンソールで [バケット] ページに移動します。

   [バケット] に移動

2. [名前] 列で、前の手順で作成したバケットの名前をクリックします。

3. [バケットの詳細] ページで、WORK_DIRECTORY フォルダを含む行を選択し、次の操作を行います。

   1. [削除] をクリックします。

   2. 確定するには、「DELETE」と入力して [削除] をクリックします。

gcloud

gcloud CLI を使用して Cloud Storage バケットから WORK_DIRECTORY フォルダとすべての出力ファイルを削除するには、--recursive フラグで gcloud storage rm コマンドを実行します。

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

以下を置き換えます。

• BUCKET_NAME: 前の手順で指定したバケットの名前。

• WORK_DIRECTORY: 前の手順で指定したパイプライン出力ファイルを保存するディレクトリ。

次のステップ

• Nextflow ワークフローのデプロイの詳細については、Nextflow GitHub リポジトリをご覧ください。

• Nextflow のプロセス、スクリプト、構成オプションの詳細については、Nextflow のドキュメントをご覧ください。