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

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

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

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

    gcloud init

  5. 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 プロジェクトの名前に置き換えます。

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

  7. 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

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

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

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

    gcloud init

  11. 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 プロジェクトの名前に置き換えます。

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

  13. 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
    14.

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

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

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

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

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

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

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

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

プロジェクトの削除

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

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

    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

以下を置き換えます。

次のステップ