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

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

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

目標

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

費用

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

  • Batch
  • Cloud Storage

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

假設您及時完成所有步驟 (包括清除作業)，本教學課程建立的資源通常不會產生超過一美元的費用。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. 安裝 Google Cloud CLI。

  3. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  4. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  5. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 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，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

  8. 安裝 Google Cloud CLI。

  9. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  10. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  11. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 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，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

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

    每項工作都需要服務帳戶，Batch 服務代理程式才能建立及存取執行工作所需的資源。在本教學課程中，這項工作的服務帳戶是 Compute Engine 預設服務帳戶。

    為確保 Compute Engine 預設服務帳戶具備必要權限，允許 Batch 服務代理程式為 Batch 作業建立及存取資源，請要求管理員將下列 IAM 角色授予 Compute Engine 預設服務帳戶：

    • Batch Agent 回報者 (roles/batch.agentReporter) 專案
    • 專案的儲存空間管理員 (roles/storage.admin)
    • (建議) 讓作業在 Cloud Logging 中產生記錄： 專案的「記錄檔寫入者」 (roles/logging.logWriter)

    如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

    管理員或許也能透過自訂角色或其他預先定義的角色，將必要權限授予 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 Genomes Project 的 BAM 檔案建立索引，並將結果輸出至 Cloud Storage bucket。

如要執行範例 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 pipeline 會執行 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 收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免付費，最簡單的方法就是刪除目前的專案。

    刪除 Google Cloud 專案：

    gcloud projects delete PROJECT_ID

刪除個別資源

如要繼續使用目前的專案，請刪除本教學課程中使用的個別資源。

刪除值區

管道執行完畢後，會在 Cloud Storage 值區的 WORK_DIRECTORY 目錄中建立並儲存輸出檔案。

如要減少目前Google Cloud 帳戶的 Cloud Storage 費用，請採取下列任一做法：

  • 如果您不再需要本教學課程中使用的 bucket，請使用帶有 --recursive 標記的 gcloud storage rm 指令，刪除 bucket 和所有內容：

    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。

後續步驟