本教學課程說明如何在 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。
假設您及時完成所有步驟 (包括清除作業),本教學課程建立的資源通常不會產生超過 $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.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
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 -
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
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 -
確認專案至少有一個服務帳戶,且該帳戶具備本教學課程所需的權限。
每個作業都需要服務帳戶,Batch 服務代理程式才能建立及存取執行作業所需的資源。在本教學課程中,作業的服務帳戶是 Compute Engine 預設服務帳戶。
為確保 Compute Engine 預設服務帳戶具備必要權限,允許 Batch 服務代理建立及存取 Batch 作業的資源,請要求管理員授予 Compute Engine 預設服務帳戶下列 IAM 角色:
-
批次工作代理程式回報者 (
roles/batch.agentReporter
) 專案 -
專案的儲存空間管理員 (
roles/storage.admin
) -
(建議) 讓作業在 Cloud Logging 中產生記錄:
專案的「記錄檔寫入者」 (
roles/logging.logWriter
) 角色
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
-
批次工作代理程式回報者 (
-
請確認您具備本教學課程所需的權限。
如要取得完成本教學課程所需的權限,請要求管理員授予下列 IAM 角色:
-
批次工作編輯者 (
roles/batch.jobsEditor
) 專案 -
服務帳戶使用者 (
roles/iam.serviceAccountUser
) 在作業的服務帳戶上,本教學課程使用的是 Compute Engine 預設服務帳戶 -
專案的Storage 物件管理員 (
roles/storage.objectAdmin
)
-
批次工作編輯者 (
-
安裝
dsub
及其依附元件。詳情請參閱dsub
安裝說明文件。請確認您已安裝最新版
dsub
支援的 Python 和 pip 版本。如要查看目前安裝的版本,請執行下列指令:pip --version
如需安裝或更新
pip
或 Python,請按照安裝 Python 的步驟操作。建議:為避免安裝
dsub
時發生依附元件衝突錯誤,請建立並啟用 Python 虛擬環境:python -m venv dsub_libs && source dsub_libs/bin/activate
使用
git
複製dsub
GitHub 存放區,然後開啟:git clone https://github.com/databiosphere/dsub.git && cd dsub
安裝
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。
後續步驟
- 進一步瞭解
dsub
和dsub
for Batch。 - 進一步瞭解如何搭配 Batch 使用儲存空間磁碟區。