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

---

このチュートリアルでは、Batch で dsub パイプラインを実行する方法について説明します。具体的には、dsub パイプラインの例では、Binary Alignment Map（BAM）ファイルで DNA 配列データを処理し、BAM インデックス（BAI）ファイルを作成します。

このチュートリアルは、Batch で dsub を使用する Batch ユーザーを対象としています。dsub は、Google Cloud でバッチ処理ワークフローをオーケストレートするためのオープンソース ジョブ スケジューラです。dsub で Batch を使用する方法の詳細については、Batch の dsub ドキュメントをご覧ください。

目標

• Cloud Storage バケット内のファイルの読み取りと書き込みを行う Batch で dsub パイプラインを実行します。
• Cloud Storage バケット内の出力ファイルを表示します。

費用

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

• Batch
• Cloud Storage

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。 新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

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

始める前に

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.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   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.

5. Make sure that billing is enabled for your Google Cloud project.

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

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

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   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.

10. Make sure that billing is enabled for your Google Cloud project.

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

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

12. プロジェクトに、このチュートリアルで必要な権限を含むサービス アカウントが 1 つ以上設定されていることを確認します。

    注: 新しいプロジェクトを使用している場合は、デフォルトのサービス アカウントに対する自動的なロール付与を組織が禁止している場合を除き、この手順を行う必要はありません。デフォルトでは、Compute Engine のデフォルトのサービス アカウントには編集者（roles/editor）IAM ロールが自動的に付与されます。このロールには、このチュートリアルで必要な権限がすでに含まれています。

    各ジョブには、Batch サービス エージェントがジョブの実行に必要なリソースを作成してアクセスできるサービス アカウントが必要です。このチュートリアルでは、ジョブのサービス アカウントは Compute Engine のデフォルトのサービス アカウントです。

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

    • プロジェクトに対するバッチ エージェント報告者（roles/batch.agentReporter）
    • プロジェクトに対するストレージ管理者（roles/storage.admin）
    • （推奨）ジョブで Cloud Logging のログを生成できるようにする プロジェクトに対するログ書き込み（roles/logging.logWriter）

    ロールの付与の詳細については、アクセスの管理をご覧ください。

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

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

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

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

    • プロジェクトのバッチジョブ編集者（roles/batch.jobsEditor）
    • ジョブのサービス アカウントに対するサービス アカウント ユーザー（roles/iam.serviceAccountUser）。このチュートリアルでは、Compute Engine のデフォルトのサービス アカウントです。
    • プロジェクトに対する Storage オブジェクト管理者（roles/storage.objectAdmin）

14. dsub とその依存関係をインストールします。詳細については、dsub のインストール ドキュメントをご覧ください。

    1. dsub の最新バージョンでサポートされているバージョンの Python と pip がインストールされていることを確認します。現在インストールされているバージョンを表示するには、次のコマンドを実行します。

       pip --version
       

       pip または Python をインストールまたは更新する必要がある場合は、Python のインストール手順をご覧ください。

    2. 推奨: dsub のインストール時に依存関係の競合エラーを回避するには、Python 仮想環境を作成して有効にします。

       python -m venv dsub_libs && source dsub_libs/bin/activate
       

    3. git を使用して dsub GitHub リポジトリのクローンを作成し、開きます。

       git clone https://github.com/databiosphere/dsub.git && cd dsub
       

    4. dsub とその依存関係をインストールします。

       python -m pip install .
       

       出力は次のようになります。

       ...
       Successfully installed cachetools-5.3.1 certifi-2023.7.22 charset-normalizer-3.3.1 dsub-0.4.9 funcsigs-1.0.2 google-api-core-2.11.0 google-api-python-client-2.85.0 google-auth-2.17.3 google-auth-httplib2-0.1.0 google-cloud-batch-0.10.0 googleapis-common-protos-1.61.0 grpcio-1.59.0 grpcio-status-1.59.0 httplib2-0.22.0 idna-3.4 mock-4.0.3 parameterized-0.8.1 proto-plus-1.22.3 protobuf-4.24.4 pyasn1-0.4.8 pyasn1-modules-0.2.8 pyparsing-3.1.1 python-dateutil-2.8.2 pytz-2023.3 pyyaml-6.0 requests-2.31.0 rsa-4.9 six-1.16.0 tabulate-0.9.0 tenacity-8.2.2 uritemplate-4.1.1 urllib3-2.0.7
       

Cloud Storage バケットを作成する

gcloud CLI を使用してサンプル dsub パイプラインからの出力ファイルを保存する Cloud Storage バケットを作成するには、gcloud storage buckets create コマンドを実行します。

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

次のように置き換えます。

• BUCKET_NAME: 実際のプロジェクトのグローバルに一意の名前。

• PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

出力は次のようになります。

Creating gs://BUCKET_NAME/...

dsub パイプラインを実行する

サンプル dsub パイプラインは、1,000 人ゲノム プロジェクトの BAM ファイルをインデックスに登録し、その結果を Cloud Storage バケットに出力します。

サンプルの dsub パイプラインを実行するには、次の dsub コマンドを実行します。

dsub \
    --provider google-batch \
    --project PROJECT_ID \
    --logging gs://BUCKET_NAME/WORK_DIRECTORY/logs \
    --input BAM=gs://genomics-public-data/1000-genomes/bam/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam \
    --output BAI=gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai \
    --image quay.io/cancercollaboratory/dockstore-tool-samtools-index \
    --command 'samtools index ${BAM} ${BAI}' \
    --wait

次のように置き換えます。

• PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

• BUCKET_NAME: 作成した Cloud Storage バケットの名前。

• WORK_DIRECTORY: パイプラインがログと出力の保存に使用できる新しいディレクトリの名前。たとえば、「workDir」と入力します。

dsub パイプラインは、BAI ファイルとログを Cloud Storage バケット内の指定されたディレクトリに書き込む Batch ジョブを実行します。具体的には、dsub リポジトリには、samtools を使用して --input フラグで指定した BAM ファイルをインデックスに登録するビルド済みの Docker イメージが含まれています。

このコマンドは、dsub パイプラインの実行が完了するまで終了しません。これは、Batch ジョブがいつスケジュールされるかによって異なります。通常、これには約 10 分かかります。Batch は通常、数分以内にジョブの実行を開始します。ジョブのランタイムは約 8 分です。

最初は、コマンドはまだ実行されており、出力は次のようになります。

Job properties:
  job-id: JOB_NAME
  job-name: samtools
  user-id: USERNAME
Provider internal-id (operation): projects/PROJECT_ID/locations/us-central1/jobs/JOB_NAME
Launched job-id: JOB_NAME
To check the status, run:
  dstat --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME' --status '*'
To cancel the job, run:
  ddel --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME'
Waiting for job to complete...
Waiting for: JOB_NAME.

ジョブが正常に終了すると、コマンドが終了し、出力は次のようになります。

  JOB_NAME: SUCCESS
JOB_NAME

この出力には次の値が含まれます。

• JOB_NAME: ジョブの名前。

• USERNAME: Google Cloud ユーザー名。

• PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

出力ファイルを表示する

gcloud CLI を使用してサンプル dsub パイプラインによって作成された出力ファイルを表示するには、gcloud storage ls コマンドを実行します。

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

次のように置き換えます。

• BUCKET_NAME: 作成した Cloud Storage バケットの名前。

• WORK_DIRECTORY: dsub コマンドで指定したディレクトリ。

• PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

出力は次のようになります。

gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/

この出力には、BAI ファイルとジョブのログを含むディレクトリが含まれています。

クリーンアップ

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

プロジェクトの削除

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

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

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

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

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

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

バケットの削除

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

現在の Google Cloud アカウントに対する Cloud Storage の料金を減らすには、次のいずれかを行います。

• このチュートリアルで使用したバケットが不要になった場合は、--recursive フラグを指定して gcloud storage rm コマンドを使用し、バケットとそのすべてのコンテンツを削除します。

  gcloud storage rm gs://BUCKET_NAME \
      --recursive \
      --project PROJECT_ID
  

  次のように置き換えます。

  • BUCKET_NAME: 作成した Cloud Storage バケットの名前。

  • PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

• まだバケットが必要な場合は、--recursive フラグを指定して gcloud storage rm コマンドを使用し、WORK_DIRECTORY ディレクトリとそのすべてのコンテンツのみを削除します。

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

  次のように置き換えます。

  • BUCKET_NAME: 作成した Cloud Storage バケットの名前。

  • WORK_DIRECTORY: dsub コマンドで指定したディレクトリ。

  • PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

ジョブを削除する

gcloud CLI を使用してジョブを削除するには、gcloud batch jobs delete コマンドを実行します。

gcloud batch jobs delete JOB_NAME \
    --location us-central1 \
    --project PROJECT_ID

次のように置き換えます。

• JOB_NAME: ジョブの名前。
• PROJECT_ID: Google Cloud プロジェクトの プロジェクト ID。

次のステップ

• dsub と Batch 用の dsubの詳細を確認する。
• Batch でのストレージ ボリュームの使用の詳細を確認する。