运行 Nextflow

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

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

目标

完成本教程后,您将了解如何执行以下任务:

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

费用

本教程使用 Google Cloud 的计费组件,包括:

  • Compute Engine
  • Cloud Storage

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

准备工作

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册新帐号

  2. 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。

    转到项目选择器页面

  3. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能

  4. 启用 Cloud Life Sciences, Compute Engine, and Cloud Storage API。

    启用 API

创建 Cloud Storage 存储分区

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

控制台

  1. 在 Cloud Console 中打开 Cloud Storage 浏览器:

    转到 Cloud Storage 浏览器

  2. 点击创建存储分区

  3. 存储分区名称文本框中,输入存储分区的唯一名称,然后点击创建

gcloud

  1. 打开 Cloud Shell:

    转到 Cloud Shell

  2. 运行以下命令以创建存储分区,其中将 BUCKET 替换为存储分区的唯一名称。

    gsutil mb gs://BUCKET
    

创建服务帐号并添加角色

如需创建服务帐号并添加相关 IAM 角色,请完成以下步骤:

控制台

使用 Cloud Console 创建服务帐号:

  1. 在 Cloud Console 中,转到服务帐号页面。

    转到“服务帐号”页面

  2. 点击创建服务帐号

  3. 服务帐号名称字段中,输入 nextflow-service-account,然后点击创建

  4. 向此服务帐号授予对项目的访问权限部分中,从选择角色下拉列表中选择以下角色:

    • Cloud Life Sciences Workflows Runner
    • 服务帐号用户
    • Service Usage Consumer
    • Storage Object Admin
  5. 点击继续,然后点击完成

  6. “服务帐号”页面中,找到您创建的服务帐号。在同一行中,点击更多,然后点击创建密钥

  7. 在出现的为“nextflow-service-account”创建私钥窗口中,完成以下步骤:

    1. 密钥类型下,选择 JSON
    2. 点击创建

    包含密钥的 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. 该服务帐号需要以下 Identity and Access Management 角色:

    • 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. 将私钥文件设置为 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=20.10.0
    export NXF_MODE=google
    curl https://get.nextflow.io | bash
    

    如果安装成功,系统会显示以下消息:

        N E X T F L O W
    version 20.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 20.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 存储分区中的输出。将 BUCKETWORK_DIR 更新为 nextflow.config 文件中指定的变量。

    gsutil ls gs://BUCKET/WORK_DIR
    
  3. 输出会为每个运行的任务显示一个文件夹。继续列出后续子目录的内容,以查看该流水线创建的所有文件。将 TASK_FOLDER 更新为通过上方命令列出的任务文件夹之一。

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

学完“运行 GATK 最佳做法流水线”教程之后,您可以清理在 Google Cloud 上创建的资源,以避免占用配额,日后产生费用。以下部分介绍如何删除或关闭这些资源。

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

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

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

gsutil du -sh gs://BUCKET/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 目录中的所有中间文件,请运行以下命令:

    gsutil -m rm gs://BUCKET/WORK_DIR/**
    

删除项目

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

如需删除项目,请执行以下操作:

  1. 在 Cloud Console 中,转到管理资源页面。

    转到“管理资源”

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

后续步骤