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

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

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

  6. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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

  8. Install the Google Cloud CLI.

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

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

    gcloud init

  11. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

  12. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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

  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

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

    プロジェクトの削除

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

      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

    以下を置き換えます。

    次のステップ