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

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

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

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

目標

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

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

費用

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

Batch
Cloud Storage

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

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

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

始める前に

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud CLI をインストールします。

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

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

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

Batch、Cloud Storage、Compute Engine、Logging の各 API を有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

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

Google Cloud CLI をインストールします。

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

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

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

Batch、Cloud Storage、Compute Engine、Logging の各 API を有効にします。

API を有効にするために必要なロール

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

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

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

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

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

このチュートリアルの 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）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

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

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

このチュートリアルを完了するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。
- プロジェクトに対する Batch ジョブ編集者（roles/batch.jobsEditor）
- ジョブのサービスアカウントに対するサービスアカウントユーザー（roles/iam.serviceAccountUser）
- プロジェクトに対する Storage オブジェクト管理者（roles/storage.objectAdmin）

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 バケットを作成する手順は次のとおりです。

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

[バケット] に移動
[ 作成] をクリックします。
[バケットの作成] ページで、バケットのグローバルに一意の名前を入力します。
[作成] をクリックします。
[公開アクセスの防止] ウィンドウで [確認] をクリックします。

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 パイプラインを構成するには、コマンドラインで次の手順を行います。

サンプルパイプラインリポジトリのクローンを作成します。
```
git clone https://github.com/nextflow-io/rnaseq-nf.git
```
rnaseq-nf フォルダに移動します。
```
cd rnaseq-nf
```

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

nano nextflow.config

このファイルには、次の 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'
}

[google-batch] セクションで、次の操作を行います。
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 のドキュメントをご覧ください。
編集内容を保存する手順は次のとおりです。
1. Control+S キーを押します。
2. 「Y」と入力します。
3. Enter キーを押します。

パイプラインを実行する

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

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

パイプラインは、前の手順で指定した設定を使用して小さなデータセットを実行します。このオペレーションが完了するまでに 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 コンソールを使用してパイプラインの出力ファイルを確認する手順は次のとおりです。

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

[バケット] に移動
[名前] 列で、前の手順で作成したバケットの名前をクリックします。
[バケットの詳細] ページで、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）を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースだけを削除します。

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

Google Cloud コンソールで [リソースの管理] ページに移動します。
[リソースの管理] に移動
プロジェクトリストで、削除するプロジェクトを選択し、[削除] をクリックします。
ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。

gcloud

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

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

Google Cloud プロジェクトを削除します。

gcloud projects delete PROJECT_ID

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

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

バケットの削除

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

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

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

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

コンソール

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

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

[バケット] に移動
[名前] 列で、前の手順で作成したバケットの名前をクリックします。
[バケットの詳細] ページで、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 のドキュメントをご覧ください。

Batch で Nextflow パイプラインを実行してジョブをオーケストレート コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標

費用

始める前に

Cloud Storage バケットを作成する

コンソール

gcloud

Nextflow を構成する

パイプラインを実行する

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

コンソール

gcloud

クリーンアップ

プロジェクトの削除

コンソール

gcloud

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

バケットの削除

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

コンソール

gcloud

次のステップ

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