透過 Batch 執行 Nextflow 管道，藉此自動化調度工作

本教學課程說明如何在 Batch 上執行 Nextflow 管道。具體來說，本教學課程會從 Nextflow 執行範例 rnaseq-nf 生命科學管道，該管道會使用 RNA-Seq 從短讀取資料量化基因體特徵。

本教學課程適用於想要搭配 Batch 使用 Nextflow 的 Batch 使用者。

Nextflow 是開放原始碼軟體，可自動化調度管理生物資訊工作流程。

目標

完成本教學課程後，您將學會如何執行下列操作：

在 Cloud Shell 中安裝 Nextflow。
建立 Cloud Storage bucket。
設定 Nextflow 管道。
使用 Nextflow 在 Batch 上執行管道範例。
查看管道的輸出內容。
如要清除所用資源，以免產生額外費用，請採取下列任一做法：
- 刪除專案。
- 刪除個別資源。

費用

在本文件中，您會使用下列 Google Cloud的計費元件：

Batch
Cloud Storage

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

假設您及時完成所有步驟 (包括清除作業)，本教學課程建立的資源通常不會產生超過一美元的費用。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
建立專案：如要建立專案，您需要具備專案建立者角色 (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，您需要具備服務使用情形管理員 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 角色，只要您已獲授角色，即可選取任何專案。
建立專案：如要建立專案，您需要具備專案建立者角色 (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，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

請確認專案的虛擬私有雲網路具有適用於本教學課程的有效網路設定。

注意：除非貴機構啟用 compute.skipDefaultNetworkCreation 政策限制來停用 default 網路建立功能，或專案已修改 default 網路，否則這個步驟不需要採取任何行動。

本教學課程假設您使用 default 網路。根據預設， Google Cloud 資源會使用 default 網路，這個網路提供本教學課程所需的網路存取權。

目標：如要讓 Nextflow 管道的 Batch 工作使用其他網路，可以選擇修改本教學課程中的 nextflow.config 檔案，分別使用 google.batch.network 和 google.batch.subnetwork Nextflow 欄位定義工作網路和子網路。不過，您也必須確保網路和子網路已為工作負載正確設定。詳情請參閱「批次網路總覽」。

請確認專案至少有一個服務帳戶，且該帳戶具備在本教學課程中執行 Batch 工作所需的權限。

根據預設，作業會使用 Compute Engine 預設服務帳戶，系統會自動授予該帳戶編輯者 (roles/editor) IAM 角色，且該帳戶已具備本教學課程所需的所有權限。

注意：除非貴機構啟用 iam.automaticIamGrantsForDefaultServiceAccounts 政策限制，禁止自動為預設服務帳戶授予權限，否則這個步驟不需要任何動作。此外，如果專案已修改 Compute Engine 預設服務帳戶，或是您想使用其他服務帳戶，也需要採取行動。

為確保工作服務帳戶具備必要權限，允許 Batch 服務代理程式建立及存取 Batch 工作資源，請要求管理員將下列 IAM 角色授予工作服務帳戶：

重要事項：您必須將這些角色授予作業的服務帳戶，而非使用者帳戶。如果未將角色授予正確的主體，可能會導致權限錯誤。
- Batch Agent 回報者 (roles/batch.agentReporter) 專案
- 專案的儲存空間管理員 (roles/storage.admin)
- (建議) 讓作業在 Cloud Logging 中產生記錄：專案的「記錄檔寫入者」 (roles/logging.logWriter)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，將必要權限授予這項工作的服務帳戶。

請確認您具備本教學課程所需的權限。

注意：如果您已建立要在本教學課程中使用的專案，則無須採取任何行動。身為專案建立者，系統會自動授予您擁有者 (roles/owner) IAM 角色，該角色已具備本教學課程所需的所有權限。

如要取得完成本教學課程所需的權限，請要求管理員授予您下列 IAM 角色：
- 批次工作編輯者 (roles/batch.jobsEditor) 專案
- 服務帳戶使用者 (roles/iam.serviceAccountUser) 在工作的服務帳戶中
- 專案的Storage 物件管理員 (roles/storage.objectAdmin)

安裝 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 bucket，儲存 Nextflow 管道的暫時工作和輸出檔案，請使用 Google Cloud 控制台或指令列。

控制台

如要使用 Google Cloud 控制台建立 Cloud Storage 值區，請按照下列步驟操作：

前往 Google Cloud 控制台的「Bucket」頁面。

前往「Buckets」(值區) 頁面
點選「建立」。
在「建立 bucket」頁面中，為 bucket 輸入全域不重複的名稱。
點選「建立」。
在「Public access will be prevented」(系統會禁止公開存取) 視窗中，按一下「Confirm」(確認)。

gcloud

如要使用 Google Cloud CLI 建立 Cloud Storage bucket，請使用 gcloud storage buckets create 指令。

gcloud storage buckets create gs://BUCKET_NAME

將 BUCKET_NAME 替換成 bucket 的全域不重複名稱。

如果要求成功，輸出內容應如下所示：

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

設定 Nextflow

如要設定 Nextflow pipeline 在 Batch 上執行，請在指令列中按照下列步驟操作：

複製範例管道存放區：

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

前往 rnaseq-nf 資料夾：
```
cd rnaseq-nf
```

開啟 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'
}

在 google-batch 部分，執行下列操作：
1. 將 BUCKET_NAME 替換為您在先前步驟中建立的 Cloud Storage bucket 名稱。
2. 將 WORK_DIRECTORY 替換為新資料夾的名稱，管道可使用該資料夾儲存記錄和輸出內容。
  
  例如輸入 workDir。
3. 將 REGION 替換為要使用的地區。
  
  例如輸入 us-central1。
4. 在 google.region 欄位後面加入下列欄位：
  1. 新增 google.project 欄位：
```
google.project = 'PROJECT_ID'
```
    將 PROJECT_ID 替換為目前專案的專案 ID。 Google Cloud
  2. 如果不是使用 Compute Engine 預設服務帳戶做為工作服務帳戶，請新增 google.batch.serviceAccountEmail 欄位：
```
google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
```
    將 SERVICE_ACCOUNT_EMAIL 替換為您為本教學課程準備的作業服務帳戶電子郵件地址。
  目標： 如要瞭解可指定的所有欄位，以便為 Nextflow 管道設定 Batch 工作，請參閱 Batch 設定範圍的 Nextflow 說明文件。
如要儲存編輯內容，請按照下列步驟操作：
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 bucket 的 WORK_DIRECTORY 資料夾中，管道的輸出檔案，可以使用 Google Cloud 控制台或指令列。

控制台

如要使用 Google Cloud 控制台檢查管道的輸出檔案，請按照下列步驟操作：

前往 Google Cloud 控制台的「Bucket」頁面。

前往「Buckets」(值區) 頁面
在「Name」(名稱) 欄中，按一下您在先前步驟中建立的值區名稱。
在「Bucket details」(值區詳細資料) 頁面中，開啟 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。

控制台

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

gcloud

刪除 Google Cloud 專案：

gcloud projects delete PROJECT_ID

刪除個別資源

如要繼續使用目前的專案，請刪除本教學課程中使用的個別資源。

刪除值區

如果您不再需要本教學課程中使用的 bucket，請刪除 bucket。

刪除值區中的輸出檔案

管道執行完畢後，會在 Cloud Storage bucket 的 WORK_DIRECTORY 資料夾中建立並儲存輸出檔案。

如要減少目前帳戶的 Cloud Storage 費用，可以使用 Google Cloud 控制台或指令列，刪除含有管道輸出檔案的資料夾。Google Cloud

控制台

如要使用Google Cloud 控制台，從 Cloud Storage bucket 刪除 WORK_DIRECTORY 資料夾和所有輸出檔案，請按照下列步驟操作：

前往 Google Cloud 控制台的「Bucket」頁面。

前往「Buckets」(值區) 頁面
在「Name」(名稱) 欄中，按一下您在先前步驟中建立的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面中，選取包含 WORK_DIRECTORY 資料夾的資料列，然後執行下列操作：
1. 點選「刪除」。
2. 如要確認，請輸入 DELETE，然後按一下「刪除」。

gcloud

如要使用 gcloud CLI 從 Cloud Storage bucket 刪除 WORK_DIRECTORY 資料夾和所有輸出檔案，請使用 gcloud storage rm 指令和 --recursive 旗標。

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

更改下列內容：

BUCKET_NAME：您在先前步驟中指定的 bucket 名稱。
WORK_DIRECTORY：用於儲存您在上一個步驟中指定的管道輸出檔案的目錄。

後續步驟

如要進一步瞭解如何部署 Nextflow 工作流程，請參閱 Nextflow GitHub 存放區。
如要進一步瞭解 Nextflow 程序、指令碼和設定選項，請參閱 Nextflow 說明文件。

透過 Batch 執行 Nextflow 管道，藉此自動化調度工作 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

建立 Cloud Storage 值區

控制台

gcloud

設定 Nextflow

執行管道

查看管道的輸出內容

控制台

gcloud

清除所用資源

刪除專案

控制台

gcloud

刪除個別資源

刪除值區

刪除值區中的輸出檔案

控制台

gcloud

後續步驟

透過 Batch 執行 Nextflow 管道，藉此自動化調度工作