通过在 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 美元。

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. Install the Google Cloud CLI.
  3. To initialize the gcloud CLI, run the following command:

    gcloud init
  4. 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.

  5. 确保您的 Google Cloud 项目已启用结算功能

  6. 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
  7. Install the Google Cloud CLI.
  8. To initialize the gcloud CLI, run the following command:

    gcloud init
  9. 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.

  10. 确保您的 Google Cloud 项目已启用结算功能

  11. 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
  12. 确保您的项目至少有一个服务账号,且该账号具有本教程所需的权限。

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

    为了确保 Compute Engine 默认服务账号具备必要的 允许 Batch 服务代理创建和访问 Batch 作业的资源。 请让管理员向 Compute Engine 默认服务账号授予 以下 IAM 角色:

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

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

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

    如需获取完成本教程所需的权限, 请让管理员授予您 以下 IAM 角色:

  14. 安装 dsub 及其依赖项。有关详情,请参阅 dsub 安装文档

    1. 确保您已安装 Pythonpip (由最新版 dsub 提供支持)。 如需查看当前安装的版本,请运行以下命令:

      pip --version
      

      如果您需要安装或更新 pip 或 Python,请按照安装 Python 的步骤操作。

    2. 建议:为防止在安装 dsub 时出现依赖项冲突错误, 创建并激活 Python 虚拟环境

      python -m venv dsub_libs && source dsub_libs/bin/activate
      
    3. 使用以下命令克隆 dsub GitHub 代码库: git 然后打开它:

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

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

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

替换以下内容:

输出类似于以下内容:

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

后续步骤