在 Batch 上執行 dsub 管道，藉此自動化調度工作

本教學課程說明如何在 Batch 上執行 dsub pipeline。具體來說，這個範例 dsub 管道會處理二進位對齊對應 (BAM) 檔案 中的 DNA 序列資料，建立 BAM 索引 (BAI) 檔案。

本教學課程適用於想要搭配 Batch 使用 dsub 的 Batch 使用者。dsub 是開放原始碼作業排程器，可自動化調度 Google Cloud上的批次處理工作流程。如要進一步瞭解如何搭配使用 Batch 與 dsub，請參閱 Batch 的 dsub 說明文件。

目標

  • 在 Batch 上執行 dsub 管道，讀取及寫入 Cloud Storage 值區中的檔案。
  • 在 Cloud Storage bucket 中查看輸出檔案。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

  • Batch
  • Cloud Storage

如要根據預測用量估算費用，請使用 Pricing Calculator。 初次使用 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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  5. Create or select a Google Cloud 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.

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

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

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  11. Create or select a Google Cloud 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.

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

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

  14. 確認專案至少有一個服務帳戶，且該帳戶具備本教學課程所需的權限。

    每個作業都需要服務帳戶，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 建立 Cloud Storage bucket，以便儲存範例 dsub 管道的輸出檔案，請執行 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 bucket 名稱。

  • WORK_DIRECTORY：管道可用來儲存記錄和輸出的新目錄名稱。例如輸入 workDir。

dsub 管道會執行 Batch 工作，將 BAI 檔案和記錄寫入 Cloud Storage bucket 中的指定目錄。具體來說，dsub 存放區包含預先建構的 Docker 映像檔，該映像檔使用 samtools 為您在 --input 旗標中指定的 BAM 檔案建立索引。

指令會在 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 bucket 名稱。

  • 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 bucket 名稱。

    • 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 bucket 名稱。

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

後續步驟