运行 Nextflow

---

本页面介绍如何在 Google Cloud 上运行 Nextflow 流水线。

本教程中使用的流水线是 RNA-Seq 流水线的概念验证，用于展示 Nextflow 在 Google Cloud 上的使用情况。

注意：您有责任遵守 Nextflow 许可协议和 RNAseq-NF 流水线许可协议的条款。

目标

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

• 在 Cloud Shell 中安装 Nextflow。
• 配置 Nextflow 流水线。
• 在 Google Cloud 上使用 Nextflow 运行流水线。

费用

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

• Compute Engine
• Cloud Storage

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

准备工作

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

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

4. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

7. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

   Enable the APIs

创建 Cloud Storage 存储分区

请按照存储分区命名准则中的指导创建具有唯一命名的存储分区。在本教程中，将使用该存储分区来存储临时工作和输出文件。为实现 DNS 兼容性，本教程不适用于包含下划线 (_) 的存储分区名称。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 浏览器页面：

   转到浏览器

2. 点击创建存储分区。

3. 在创建存储分区页面上，输入您的存储分区信息。

4. 点击创建。

gcloud

1. 打开 Cloud Shell：

   转到 Cloud Shell

2. 使用 gcloud storage buckets create 命令：

   gcloud storage buckets create gs://BUCKET_NAME
   

   根据命名要求，将 BUCKET_NAME 替换为您要提供给存储分区的名称。例如 my-bucket。

   如果请求成功，该命令将返回以下消息：

   Creating gs://BUCKET_NAME/...
   

创建服务账号并添加角色

完成以下步骤以创建服务账号并添加以下 Identity and Access Management 角色：

• Cloud Life Sciences Workflows Runner
• 服务账号用户
• Service Usage Consumer

• Storage Object Admin

控制台

使用 Google Cloud 控制台创建服务账号：

1. 在 Google Cloud 控制台中，转到服务账号页面。

   转到“服务账号”页面

2. 点击创建服务账号。

3. 在服务账号名称字段中，输入 nextflow-service-account，然后点击创建。

4. 在向此服务账号授予对项目的访问权限部分中，从选择角色下拉列表中添加以下角色：

   • Cloud Life Sciences Workflows Runner
   • 服务账号用户
   • Service Usage Consumer
   • Storage Object Admin

5. 点击继续，然后点击完成。

6. 在“服务账号”页面中，找到您创建的服务账号。在服务账号所在的行中，点击 更多 按钮，然后点击 管理密钥。

7. 在密钥页面上，点击添加密钥，然后点击创建新密钥。

8. 选择 JSON 作为密钥类型，然后点击创建。

   包含密钥的 JSON 文件就会下载到您的计算机。

gcloud

使用 Cloud Shell 完成以下步骤：

1. 打开 Cloud Shell。

   转到 Cloud Shell

2. 设置要在创建服务账号时使用的变量，将 PROJECT_ID 替换为您的项目 ID。

   export PROJECT=PROJECT_ID
   export SERVICE_ACCOUNT_NAME=nextflow-service-account
   export SERVICE_ACCOUNT_ADDRESS=${SERVICE_ACCOUNT_NAME}@${PROJECT}.iam.gserviceaccount.com

3. 创建服务账号。

   gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

4. 该服务账号需要具有以下 IAM 角色：

   • roles/lifesciences.workflowsRunner
   • roles/iam.serviceAccountUser
   • roles/serviceusage.serviceUsageConsumer
   • roles/storage.objectAdmin

   通过在 Cloud Shell 中运行以下命令来授予这些角色：

   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/lifesciences.workflowsRunner
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/iam.serviceAccountUser
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/serviceusage.serviceUsageConsumer
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/storage.objectAdmin

为应用提供凭据

您可以将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务账号密钥的 JSON 文件的路径，以此向应用代码或命令提供身份验证凭据。

以下步骤展示了如何设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

控制台

1. 打开 Cloud Shell。

   转到 Cloud Shell

2. 从 Cloud Shell 的更多 菜单中，选择上传文件，然后选择刚创建的 JSON 密钥文件。将该文件上传到 Cloud Shell 实例的主目录。

3. 确认已上传的文件在当前目录中并通过运行以下命令确认文件名：

   ls

4. 设置凭据，将 KEY_FILENAME.json 替换为密钥文件的名称。

   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY_FILENAME.json

gcloud

使用 Cloud Shell 完成以下步骤：

1. 打开 Cloud Shell。

   转到 Cloud Shell

2. 从 Cloud Shell 的更多 菜单中，选择上传文件，然后选择刚创建的 JSON 密钥文件。将该文件上传到 Cloud Shell 实例的主目录。

3. 确认已上传的文件在当前目录中并通过运行以下命令确认文件名：

   ls

4. 将私钥文件设置为 GOOGLE_APPLICATION_CREDENTIALS 环境变量：

   export SERVICE_ACCOUNT_KEY=${SERVICE_ACCOUNT_NAME}-private-key.json
   gcloud iam service-accounts keys create \
     --iam-account=${SERVICE_ACCOUNT_ADDRESS} \
     --key-file-type=json ${SERVICE_ACCOUNT_KEY}
   export SERVICE_ACCOUNT_KEY_FILE=${PWD}/${SERVICE_ACCOUNT_KEY}
   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/${SERVICE_ACCOUNT_KEY}

在 Cloud Shell 中安装和配置 Nextflow

为避免在您的计算机上安装任何软件，请使用 Cloud Shell 继续运行本教程中的所有终端命令。

1. 如果尚未打开，请打开 Cloud Shell。

   转到 Cloud Shell

2. 运行以下命令安装 Nextflow：

   export NXF_VER=21.10.0
   export NXF_MODE=google
   curl https://get.nextflow.io | bash

   如果安装成功，系统会显示以下消息：

       N E X T F L O W
   version 21.10.0 build 5430
   created 01-11-2020 15:14 UTC (10:14 EDT)
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   ‐ the executable file `nextflow` has been created in the folder: DIRECTORY
   ‐ you may complete the installation by moving it to a directory in your $PATH
   

3. 运行以下命令以克隆示例流水线代码库。该代码库包括要运行的流水线以及流水线使用的样本数据。

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

4. 要配置 Nextflow，请完成以下步骤：

   1. 切换到 rnaseq-nf 文件夹。

      cd rnaseq-nf
      git checkout v2.0

   2. 使用选择的文本编辑器，修改名为 nextflow.config 的文件，并对标记为 gls 的部分进行以下更新：

      • 添加 google.project 行（如果不存在）。
      • 将 PROJECT_ID 替换为您的项目 ID。
      • 如果需要，更改 google.location 的值。该值必须是当前可用的 Cloud Life Sciences API 位置之一。
      • 如果需要，更改 google.region 的值，以指定 Compute Engine 虚拟机的启动区域。请参阅可用的 Compute Engine 区域和地区。
      • 将 BUCKET 替换为之前创建的存储分区名称。
      • 将 WORK_DIR 替换为用于日志记录和输出内容的文件夹的名称。请使用您的存储分区中尚不存在的新目录名称。
      注意：workDir 变量位置必须至少包含 1 个子目录。请勿使用存储分区名称。

      gls {
         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-lifesciences'
         process.container = 'nextflow/rnaseq-nf:latest'
         workDir = 'gs://BUCKET/WORK_DIR'
         google.location = 'europe-west2'
         google.region  = 'europe-west1'
         google.project = 'PROJECT_ID'
      }

   3. 转到上一个文件夹

      cd ..

使用 Nextflow 运行流水线

使用 Nextflow 运行流水线。启动流水线后，它将继续在后台运行，直到完成。流水线最多可能需要 10 分钟才能完成。

./nextflow run rnaseq-nf/main.nf -profile gls

流水线完成后，系统将显示以下消息：

N E X T F L O W  ~  version 21.10.0
Launching `rnaseq-nf/main.nf` [suspicious_mestorf] - revision: ef908c0bfd
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
executor >  google-lifesciences (4)
[db/2af640] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[a6/927725] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[59/438177] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/9743b9] process > MULTIQC                       [100%] 1 of 1 ✔
Done! Open the following report in your browser --> results/multiqc_report.html
Completed at: DATE TIME
Duration    : 10m
CPU hours   : 0.2
Succeeded   : 4

查看 Nextflow 流水线的输出

流水线完成后，您可以检查输出以及所有日志、错误、运行的命令和临时文件。

流水线将最终输出文件 results/qc_report.html 保存到您在 nextflow.config 文件中指定的 Cloud Storage 存储分区。

如需检查每个任务和中间文件中的各个输出文件，请完成以下步骤：

控制台

1. 在 Cloud Storage 控制台中，打开 Storage 浏览器页面：

   转到 Cloud Storage 浏览器

2. 转到 BUCKET 并浏览至 nextflow.config 文件中指定的 WORK_DIR。

3. 在流水线中运行的每个独立任务都有一个文件夹。

4. 该文件夹包含运行过的命令、输出文件以及曾在工作流中使用的临时文件。

gcloud

1. 如需在 Cloud Shell 中查看输出文件，请先打开 Cloud Shell：

   转到 Cloud Shell

2. 运行以下命令，列出 Cloud Storage 存储分区中的输出。将 BUCKET 和 WORK_DIR 更新为 nextflow.config 文件中指定的变量。

   gcloud storage ls gs://BUCKET/WORK_DIR

3. 输出会为每个运行的任务显示一个文件夹。继续列出后续子目录的内容，以查看该流水线创建的所有文件。 更新前面的命令中列出的 TASK_FOLDER 任务文件夹之一。

   gcloud storage ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER

您可以查看流水线创建的中间文件，并选择要保留或删除它们以降低 Cloud Storage 相关的成本。如需删除文件，请参阅删除 Cloud Storage 存储分区中的中间文件。

问题排查

• 如果您在运行流水线时遇到问题，请参阅 Cloud Life Sciences API 问题排查。

• 如果流水线发生故障，您可以检查每项任务的日志，即 Cloud Storage 中每个文件夹内的日志文件（如 .command.err、.command.log、.command.out 等）。

清除数据

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

完成本教程后，您可以清理您创建的资源，让它们停止使用配额，以免产生费用。以下部分介绍如何删除或关闭这些资源。

删除 Cloud Storage 存储分区中的中间文件

当您运行流水线时，中间文件将存储在 gs://BUCKET/WORK_DIR 中。您可以在工作流完成后移除文件，以减少 Cloud Storage 费用。

如需查看该目录中使用的空间量，请运行以下命令：

gcloud storage du gs://BUCKET/WORK_DIR --readable-sizes --summarize

如需从 WORK_DIR 中移除文件，请完成以下步骤：

控制台

1. 在 Cloud Storage 控制台中，打开 Storage 浏览器页面：

   转到 Cloud Storage 浏览器

2. 转到 BUCKET 并浏览至 nextflow.config 文件中指定的 WORK_DIR。

3. 浏览子文件夹并删除所有不需要的文件或目录。如需删除所有文件，请删除整个 WORK_DIR。

gcloud

1. 打开 Cloud Shell 并运行以下命令：

   转到 Cloud Shell

2. 如需删除 WORK_DIR 目录中的中间文件，请运行以下命令：

   gcloud storage rm gs://BUCKET/WORK_DIR/**

删除项目

为了避免产生费用，最简单的方法是删除您为本教程创建的项目。

如需删除项目，请执行以下操作：

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

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

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

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

后续步骤

以下页面提供了有关使用 Nextflow 的更多背景信息、文档和支持：

• Nextflow 网站
• Nextflow GitHub 代码库
• Nextflow 文档