此页面由 Cloud Translation API 翻译。

在 Batch 上运行 dsub 流水线以编排作业

本教程介绍了如何在批处理作业中运行 dsub 流水线。具体而言，示例 dsub 流水线会处理二进制对齐映射 (BAM) 文件中的 DNA 测序数据，以创建 BAM 索引 (BAI) 文件。

本教程面向希望将 dsub 与批处理服务搭配使用的批处理用户。dsub 是一个开源作业调度程序，用于在 Google Cloud上编排批处理工作流。如需详细了解如何将批处理与 dsub 搭配使用，请参阅 dsub 批处理文档。

目标

在批处理作业中运行 dsub 流水线，用于读取和写入 Cloud Storage 存储分区中的文件。
查看 Cloud Storage 存储分区中的输出文件。

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

Batch
Cloud Storage

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用。

如果您及时完成本教程中的所有步骤（包括清理），那么在此期间所创建资源的费用通常不会超过 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.

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.

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

确保您的项目至少有一个服务账号，且该账号具有本教程所需的权限。

注意：如果您使用的是新项目，则无需执行此步骤，除非您的组织阻止为默认服务账号自动授予角色。默认情况下，系统会自动向 Compute Engine 默认服务账号授予 Editor (roles/editor) IAM 角色，该角色已拥有本教程所需的所有权限。

每个作业都需要一个服务账号，以便让批处理服务代理能够创建和访问运行作业所需的资源。在本教程中，作业的服务账号是 Compute Engine 默认服务账号。

为确保 Compute Engine 默认服务账号具有允许批处理服务代理创建和访问批处理作业资源所需的权限，请让您的管理员向 Compute Engine 默认服务账号授予以下 IAM 角色：
- 项目的 Batch Agent Reporter (roles/batch.agentReporter)
- 项目的 Storage Admin (roles/storage.admin)
- （推荐）允许作业在 Cloud Logging 中生成日志：项目的 Logs Writer (roles/logging.logWriter)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您的管理员也可以通过自定义角色或其他预定义角色为 Compute Engine 默认服务账号授予所需的权限。

确保您拥有本教程所需的权限。

注意：如果您创建了此项目，则无需执行此步骤。作为项目创建者，您会自动获得 Owner (roles/owner) IAM 角色，该角色已拥有本教程所需的所有权限。

如需获得完成本教程所需的权限，请让您的管理员为您授予以下 IAM 角色：
- 项目的 Batch Job Editor (roles/batch.jobsEditor)
- 作业服务账号（本教程中为 Compute Engine 默认服务账号）的 Service Account User (roles/iam.serviceAccountUser)
- 项目的 Storage Object Admin (roles/storage.objectAdmin)

安装 dsub 及其依赖项。如需了解详情，请参阅 dsub 安装文档。

确保您安装的 Python 和 pip 版本受最新版本的 dsub 支持。如需查看当前安装的版本，请运行以下命令：
```
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

替换以下内容：

BUCKET_NAME：存储分区的全局唯一名称。
PROJECT_ID： Google Cloud 项目的项目 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 存储分区的名称。
WORK_DIRECTORY：新目录的名称，流水线可以使用该目录来存储日志和输出。例如，输入 workDir。

dsub 流水线会运行一个批处理作业，该作业会将 BAI 文件和日志写入 Cloud Storage 存储分区中的指定目录。具体而言，dsub 代码库包含一个预构建的 Docker 映像，该映像使用 samtools 为您在 --input 标志中指定的 BAM 文件编制索引。

该命令会在 dsub 流水线运行完毕后才会完成，具体时间可能会因批处理作业的安排时间而异。通常，此过程需要大约 10 分钟：批处理通常会在几分钟内开始运行作业，作业的运行时长约为 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

替换以下内容：

JOB_NAME：作业的名称。
PROJECT_ID： Google Cloud 项目的项目 ID。

后续步骤

详细了解 dsub 和适用于批处理的 dsub。
详细了解如何将存储卷与批处理结合使用。