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

本教程介绍如何在 Batch 上运行 dsub 流水线。具体来说，示例 dsub 流水线会处理 Binary Alignment Map (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

如需根据您的预计使用情况来估算费用，请使用价格计算器。

新 Google Cloud 用户可能有资格申请免费试用。

如果您及时完成本教程中的所有步骤（包括清理），那么在此期间所创建资源的费用通常不会超过 1 美元。

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

创建或选择 Google Cloud 项目。

选择或创建项目所需的角色

• 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
• 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (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 项目名称。

验证是否已为您的 Google Cloud 项目启用结算功能。

启用 Batch、Cloud Storage、Compute Engine 和 Logging API：

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

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

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

创建或选择 Google Cloud 项目。

选择或创建项目所需的角色

• 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
• 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (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 项目名称。

验证是否已为您的 Google Cloud 项目启用结算功能。

启用 Batch、Cloud Storage、Compute Engine 和 Logging API：

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

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

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

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

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

   为确保 Compute Engine 默认服务账号具有必要的权限，以允许 Batch 服务代理为 Batch 批量作业创建和访问资源，请让您的管理员向 Compute Engine 默认服务账号授予以下 IAM 角色：

   重要提示：您必须向 Compute Engine 默认服务账号（而不是向您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。
   • 项目的 Batch Agent Reporter (roles/batch.agentReporter)
   • 项目的 Storage Admin (roles/storage.admin)
   • （推荐）允许作业在 Cloud Logging 中生成日志： Logs Writer (roles/logging.logWriter) on the project

   如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

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

   注意：如果您创建了此项目，则无需执行此步骤。作为项目创建者，您会自动获得 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)

3. 安装 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 存储桶来存储示例 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 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。

查看输出文件

如需使用 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 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

避免产生费用的最简单方法是删除当前项目。

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

删除 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。

• 否则，如果您仍需要该存储桶，请将 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：您的 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 搭配使用。