本教程介绍了如何在 Batch 上运行 dsub
流水线。具体而言,示例 dsub
流水线处理二进制比对映射 (BAM) 文件中的 DNA 测序数据,以创建 BAM 索引 (BAI) 文件。
本教程适用于想要将 dsub
与 Batch 搭配使用的 Batch 用户。dsub
是一个开源作业调度器,用于在 Google Cloud 上编排批处理工作流。如需详细了解如何将 Batch 与 dsub
搭配使用,请参阅 Batch 的 dsub
文档。
目标
- 在 Batch 上运行
dsub
流水线,用于读取和写入 Cloud Storage 存储分区中的文件。 - 查看 Cloud Storage 存储桶中的输出文件。
费用
在本���档中,您将使用 Google Cloud 的以下收费组件:
- Batch
- Cloud Storage
您可使用价格计算器根据您的预计使用情况来估算费用。
如果您及时完成包括清理在内的所有步骤,那么本教程中创建的资源的费用通常不到 1 美元。
准备工作
- 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
- 安装 Google Cloud CLI。
-
如需初始化 gcloud CLI,请运行以下命令:
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.
-
-
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 - 安装 Google Cloud CLI。
-
如需初始化 gcloud CLI,请运行以下命令:
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.
-
-
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
) -
项目的 Storage Admin (
roles/storage.admin
) -
(推荐)允许作业在 Cloud Logging 中生成日志:
针对项目的 Logs Writer (
roles/logging.logWriter
)
如需详细了解如何授予角色,请参阅管理访问权限。
-
项目的批处理代理报告程序 (
-
确保您拥有本教程所需的权限。
如需获取完成本教程所需的权限,请让管理员向您授予以下 IAM 角色:
-
项目的 Batch Job Editor (
roles/batch.jobsEditor
) -
作业服务帐号的 Service Account User (
roles/iam.serviceAccountUser
),在本教程中为 Compute Engine 默认服务帐号 -
项目的 Storage Object Admin (
roles/storage.objectAdmin
)
-
项目的 Batch Job Editor (
-
安装
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 存储桶,用于存储示例 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 存储桶。
如需运行示例 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
代码库包含一个预构建的 Docker 映像,该映像使用 samtools
将您在 --input
标志中指定的 BAM 文件编入索引。
该命令会在 dsub
流水线完成运行后完成,具体情况可能会因批处理作业的调度时间而异。通常,此过程大约需要 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。
查看输出文件
如需查看示例 dsub
流水线使用 gcloud CLI 创建的输出文件,请运行 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
替换以下内容:
JOB_NAME
:作业的名称。PROJECT_ID
:您的 Google Cloud 项目的项目 ID。
后续步骤
- 详细了解
dsub
和 Batch 的dsub
。 - 详细了解如何将存储卷与 Batch 搭配使用。