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

本教程介绍了如何在 Batch 上运行 Nextflow 流水线。具体而言，本教程运行 Nextflow 中的 示例 rnaseq-nf生命科学流水线， 该流水线使用 RNA-Seq从短读取数据中量化基因组特征。

本教程面向想要将 Nextflow 与 Batch 搭配使用的 Batch 用户。

Nextflow 是一款用于编排生物信息学工作流的开源软件。

注意：本教程提供了有关使用此 应用（Nextflow 版本 23.04.1）的说明。这些说明可能不适用于该应用的新版本。如需了解详情，请参阅 文档： Nextflow。

目标

完成本教程后，您将了解如何执行以下操作：

• 在 Cloud Shell 中安装 Nextflow。
• 创建 Cloud Storage 存储桶。
• 配置 Nextflow 流水线。
• 在 Batch 上使用 Nextflow 运行示例流水线。
• 查看流水线的输出。
• 清理数据，以免产生额外费用，方法如下：
  • 删除项目。
  • 逐个删除资源。

费用

在本文档中，您将使用的以下收费组件： 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. 确保您的项目具有虚拟私有云 (VPC) 网络，并且该网络具有适用于本教程的有效网络配置。

   注意：除非 您的组织通过启用 compute.skipDefaultNetworkCreation 政策限制条件停用了 default 网络创建功能 或者您的项目修改了其 default 网络，否则无需执行此步骤。

   本教程假定您使用的是 default network。 默认情况下， Google Cloud 资源使用 default 网络， 该网络提供本教程所需的网络访问权限。

   目标 ：（可选）如果您希望 Nextflow 流水线的批量作业使用其他网络，您可以在本教程中修改 nextflow.config 文件，以使用 google.batch.network 和 google.batch.subnetwork Nextflow 字段分别定义作业的网络和子网。不过，您还必须确保为工作负载正确配置网络和子网。如需了解详情，请参阅 Batch 网络概览。

2. 确保您的项目至少有一个 服务账号，并且该账号具有在本 教程中运行批量作业所需的 权限。

   默认情况下，作业使用 Compute Engine 默认服务账号， 该账号会自动被授予 Editor (roles/editor) IAM 角色，并且已拥有 本教程所需的所有权限。

   注意：除非 您的组织通过启用 iam.automaticIamGrantsForDefaultServiceAccounts 政策限制条件停用了默认服务账号的自动权限， 或者您的项目修改了其 Compute Engine 默认服务帐号，或者您 想要使用其他服务帐号，否则无需执行此步骤。

   如需确保作业的服务帐号具有允许 Batch 服务代理为 Batch 作业创建和访问资源所需的权限，请让您的管理员为作业的服务帐号授予以下 IAM 角色：

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

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

   您的管理员也可以通过自定义角色或其他预定义角色向作业的服务帐号授予所需的权限。

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

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

   如需获得完成本教程所需的权限，请让您的管理员为您授予以下 IAM 角色：

   • Batch Job Editor (roles/batch.jobsEditor) on the project
   • 作业的服务帐号的 roles/iam.serviceAccountUser Service Account User
   • 项目的 Storage Object Admin (roles/storage.objectAdmin)

4. 安装 Nextflow：

   curl -s -L https://github.com/nextflow-io/nextflow/releases/download/v23.04.1/nextflow | bash
   

   输出应类似如下所示：

   N E X T F L O W
   version 23.04.1 build 5866
   created 15-04-2023 06:51 UTC
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   - the executable file `nextflow` has been created in the folder: ...
   - you may complete the installation by moving it to a directory in your $PATH
   

创建 Cloud Storage 存储桶

如需创建 Cloud Storage 存储桶来存储 Nextflow 流水线的临时工作文件和输出文件，请使用 Google Cloud 控制台或命令行。

控制台

如需使用 Google Cloud 控制台 创建 Cloud Storage 存储桶，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往存储分区 页面。

   进入“存储桶”

2. 点击 创建。

3. 在创建存储桶 页面上，为存储桶输入一个 全局唯一的名称。

4. 点击创建 。

5. 在系统将禁止公开访问 窗口中，点击确认 。

gcloud

如需使用 Google Cloud CLI 创建 Cloud Storage 存储桶， 请使用 gcloud storage buckets create 命令。

gcloud storage buckets create gs://BUCKET_NAME

将 BUCKET_NAME 替换为存储桶的 全局唯一名称。

如果请求成功，输出应类似如下所示：

Creating gs://BUCKET_NAME/...
   ```

配置 Nextflow

如需配置 Nextflow 流水线以在 Batch 上运行，请在命令行中执行以下步骤：

1. 克隆示例流水线代码库：

   git clone https://github.com/nextflow-io/rnaseq-nf.git
   

2. 转到 rnaseq-nf 文件夹：

   cd rnaseq-nf
   

3. 打开 nextflow.config 文件：

   nano nextflow.config
   

   该文件应包含以下 google-batch 部分：

   'google-batch' {
       params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'
       params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'
       params.multiqc = 'gs://rnaseq-nf/multiqc'
       process.executor = 'google-batch'
       process.container = 'docker.io/nextflow/rnaseq-nf:v1.3.1'
       /*
        * replace with your own bucket!
        */
       workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
       google.region  = 'REGION'
   }
   

4. 在 google-batch 部分中，执行以下操作：

   1. 将 BUCKET_NAME 替换为您在之前的步骤中创建的 Cloud Storage 存储桶的名称。

   2. 将 WORK_DIRECTORY 替换为流水线可用于存储日志和输出的新文件夹的名称。

      例如，输入 workDir。

   3. 将 REGION 替换为要使用的区域。

      例如，输入 us-central1。

   4. 在 google.region 字段之后，添加以下字段：

      1. 添加 google.project 字段：

         google.project = 'PROJECT_ID'
         

         将 PROJECT_ID 替换为 当前 Google Cloud 项目的项目 ID。

      2. 如果您未使用 Compute Engine 默认服务帐号作为作业的服务帐号，请添加 google.batch.serviceAccountEmail 字段：

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         将 SERVICE_ACCOUNT_EMAIL 替换为您为本教程准备的作业的服务帐号的电子邮件地址。

      目标： 如需了解可用于为 Nextflow 流水线配置 Batch 批量作业的所有字段， 请参阅 Batch 配置范围的 Nextflow 文档。

5. 如需保存所做的修改，请执行以下操作：

   1. 按 Control+S。

   2. 输入 Y。

   3. 按 Enter。

运行流水线

使用命令行运行示例 Nextflow 流水线：

../nextflow run nextflow-io/rnaseq-nf -profile google-batch

流水线使用您在之前的步骤中提供的设置运行小型数据集。此操作最多可能需要 10 分钟才能完成。

流水线运行完成后，输出应类似如下所示：

N E X T F L O W  ~  version 23.04.1
Launching `https://github.com/nextflow-io/rnaseq-nf` [crazy_curry] DSL2 - revision: 88b8ef803a [master]
 R N A S E Q - N F   P I P E L I N E
 ===================================
 transcriptome: gs://rnaseq-nf/data/ggal/transcript.fa
 reads        : gs://rnaseq-nf/data/ggal/gut_{1,2}.fq
 outdir       : results

Uploading local `bin` scripts folder to gs://example-bucket/workdir/tmp/53/2847f2b832456a88a8e4cd44eec00a/bin
executor >  google-batch (4)
[67/71b856] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[0c/2c79c6] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[a9/571723] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/1f0dd4] process > MULTIQC                       [100%] 1 of 1 ✔

Done! Open the following report in your browser --> results/multiqc_report.html

Completed at: 20-Apr-2023 15:44:55
Duration    : 10m 13s
CPU hours   : (a few seconds)
Succeeded   : 4

查看流水线的输出

流水线运行完成后，它会将输出文件、日志、错误或临时文件存储在 Cloud Storage 存储桶的 WORK_DIRECTORY 文件夹中的 results/qc_report.html 文件中。

如需在 Cloud Storage 存储桶的 WORK_DIRECTORY 文件夹中查看流水线的输出文件，您可以使用 Google Cloud 控制台或命令行。

控制台

如需使用 Google Cloud 控制台查看流水线的输出文件，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往存储分区 页面。

   进入“存储分区”

2. 在名称 列中，点击您在之前的步骤中创建的存储桶的名称。

3. 在存储分区详细信息 页面上，打开 WORK_DIRECTORY 文件夹。

工作流运行的每个独立任务都有一个文件夹。每个文件夹都包含运行过的命令、输出文件以及流水线创建的临时文件。

gcloud

如需使用 gcloud CLI 查看流水线的输出文件，请使用 gcloud storage ls命令。

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

替换以下内容：

• BUCKET_NAME：您在之前的步骤中创建的存储桶的名称。

• WORK_DIRECTORY：您在 nextflow.config 文件中指定的目录。

输出会列出流水线运行的每个独立任务的文件夹。 每个文件夹都包含运行过的命令、输出文件以及流水线创建的临时文件。

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

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

如需删除当前项目，请使用 Google Cloud 控制台或 gcloud CLI。

控制台

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

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

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

1. 在 Google Cloud 控制台中，前往 管理资源 页面。

   转到“管理资源”

2. 在项目列表中，选择要删除的项目，然后点击删除。
3. 在对话框中输入项目 ID，然后点击 关闭以删除项目。

gcloud

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

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

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

删除项目： Google Cloud

gcloud projects delete PROJECT_ID

逐个删除资源

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

删除存储桶

如果您不再需要本教程中使用的存储桶，请将其 删除。

删除存储桶中的输出文件

流水线运行完成后，它会在 Cloud Storage 存储桶的 WORK_DIRECTORY 文件夹中创建并存储输出文件。

如需减少当前 Google Cloud 账号的 Cloud Storage 费用，您可以使用控制台或命令行删除包含流水线 输出文件的文件夹。 Google Cloud

控制台

如需使用 Google Cloud 控制台从 Cloud Storage 存储桶中删除 WORK_DIRECTORY 文件夹和所有 输出文件，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往存储分区 页面。

   进入“存储分区”

2. 在名称 列中，点击您在之前的步骤中创建的存储桶的名称。

3. 在存储分区详细信息 页面上，选择包含 WORK_DIRECTORY 文件夹的行，然后执行以下操作：

   1. 点击删除 。

   2. 如需确认，请输入 DELETE，然后点击删除 。

gcloud

如需使用 gcloud CLI 从 Cloud Storage 存储桶中删除 WORK_DIRECTORY 文件夹和所有 输出文件，请使用带有 --recursive 标志的 gcloud storage rm 命令。

gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
      --recursive

替换以下内容：

• BUCKET_NAME：您在之前的步骤中指定的存储桶的名称。

• WORK_DIRECTORY：您在之前的步骤中指定的用于存储流水线输出文件的目录。

后续步骤

• 如需详细了解如何部署 Nextflow 工作流，请参阅 Nextflow GitHub 代码库。

• 如需详细了解 Nextflow 进程、脚本编写和配置选项， 请参阅 Nextflow 文档。