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

---

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

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

目標

• Cloud Storage バケット内のファイルを読み取り、書き込む dsub パイプラインを Batch で実行します。
• 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 Genomes Project の 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 バケット内の指定されたディレクトリにログを書き込むバッチジョブを実行します。具体的には、dsub リポジトリには、samtools を使用して --input フラグで指定した BAM ファイルをインデックス化する事前ビルドされた Docker イメージが含まれています。

dsub パイプラインの実行が完了するまで、コマンドは完了しません。これは、Batch ジョブのスケジュール設定時刻によって異なる場合があります。通常、この処理には 10 分ほどかかります。通常、バッチは数分以内にジョブの実行を開始し、ジョブの実行時間は約 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 でのストレージ ボリュームの使用の詳細を確認する。