此页面由 Cloud Translation API 翻译。

通过在 Batch 上运行 dsub 流水线来编排作业

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

本教程适用于想要使用 dsub 与 Batch 结合使用。 dsub 是一个开源作业调度器用于在 Google Cloud 上编排批处理工作流。详细了解如何使用使用 dsub 进行批处理，请参阅适用于 Batch 的 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 默认服务账号是已自动授予编辑者 (roles/editor) IAM 该角色已拥有本教程所需的所有权限。

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

为了确保 Compute Engine 默认服务账号具备必要的允许 Batch 服务代理创建和访问 Batch 作业的资源。请让管理员向 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) 针对项目
- Service Account User (roles/iam.serviceAccountUser) 服务账号用户针对作业的服务账号，在本教程中为 Compute Engine 默认服务账号
- 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
```

使用以下命令克隆 dsub GitHub 代码库： git 然后打开它：

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 存储桶

如需创建 Cloud Storage 存储桶来存储示例 dsub 流水线，运行 gcloud storage buckets create 命令：

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

替换以下内容：

BUCKET_NAME：a 您的存储桶的全局唯一名称。
PROJECT_ID：项目 ID Google Cloud 项目的角色

输出类似于以下内容：

Creating gs://BUCKET_NAME/...

运行 `dsub` 流水线

示例 dsub 流水线会将 BAM 文件从 1,000 Genomes 项目并将结果输出到 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：项目 ID Google Cloud 项目的角色
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。

查看输出文件

如需查看示例 dsub 流水线使用 gcloud CLI，请运行 gcloud storage ls 命令：

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

替换以下内容：

BUCKET_NAME：Cloud Storage 的名称存储桶
WORK_DIRECTORY：您在 Cloud Storage 中指定的目录 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

删除各个资源

如果您想继续使用当前项目，请删除单个本教程中使用的资源

删除存储桶

流水线运行完毕后，会在 WORK_DIRECTORY 目录存储桶。

将 Cloud Storage 费用减少到当前的 Google Cloud 账号，请执行以下操作之一：

如果您不再需要本教程中使用的存储桶，使用 gcloud storage rm 命令使用 --recursive 标志删除存储桶及其所有内容：
```
gcloud storage rm gs://BUCKET_NAME \
    --recursive \
    --project PROJECT_ID
```
替换以下内容：
- BUCKET_NAME：Cloud Storage 的名称存储桶
- PROJECT_ID：您的 Google Cloud 项目的项目 ID。
否则，如果您仍然需要存储桶，请使用 gcloud storage rm 命令 --recursive 标志，用于仅删除 WORK_DIRECTORY 目录及其所有内容：
```
gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
    --recursive \
    --project PROJECT_ID
```
替换以下内容：
- BUCKET_NAME：Cloud Storage 的名称存储桶
- WORK_DIRECTORY：您在 dsub 命令中指定的目录。
- PROJECT_ID：项目 ID Google Cloud 项目的角色

删除作业

要使用 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 用于 Batch。
详细了解如何将存储卷与批处理结合使用。