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. Google Cloud CLI をインストールします。

  3. gcloud CLI を初期化するには:

    gcloud init

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

    • Google Cloud プロジェクトを作成します。

      gcloud projects create PROJECT_ID

      PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。

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

      gcloud config set project PROJECT_ID

      PROJECT_ID は、実際の Google Cloud プロジェクト名に置き換えます。

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

  6. Batch, Cloud Storage, Compute Engine, and Logging API を有効にします。 

    gcloud services enable batch.googleapis.comcompute.googleapis.comlogging.googleapis.comstorage.googleapis.com
    7.
  7. Google Cloud CLI をインストールします。

  8. gcloud CLI を初期化するには:

    gcloud init

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

    • Google Cloud プロジェクトを作成します。

      gcloud projects create PROJECT_ID

      PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。

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

      gcloud config set project PROJECT_ID

      PROJECT_ID は、実際の Google Cloud プロジェクト名に置き換えます。

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

  11. Batch, Cloud Storage, Compute Engine, and Logging API を有効にします。 

    gcloud services enable batch.googleapis.comcompute.googleapis.comlogging.googleapis.comstorage.googleapis.com
    12.

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

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

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

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

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

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

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

  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

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

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

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 アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトの削除

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

    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。

次のステップ