AWS HealthOmics が Nextflow バージョンの実行時固定をサポートしたので試してみた

はじめに

2026 年 6 月、AWS HealthOmics が実行時の Nextflow バージョン固定をサポートしました。StartRun API に engineSettings マップを渡すだけで、ワークフローのソースコードを変えずに Nextflow のエンジンバージョンを指定できます。

https://aws.amazon.com/jp/about-aws/whats-new/2026/06/aws-healthomics-nextflow-version-pinning-at-runtime/

この記事は先に公開した次の記事をベースに追加で検証しています。

https://dev.classmethod.jp/articles/aws-healthomics-nextflow-26-04-hello-world/

前の記事は nextflow.config の manifest.nextflowVersion で定義時にバージョンを埋め込む手法を扱いました。この記事では StartRun API の engineSettings.engineVersion で実行時にバージョンをオーバーライドする新機能を試します。

確認結果

登録済みのワークフロー（id 7635166）を変更なしに 2 回 run し、run ごとに Nextflow バージョンを切り替えられることを確認しました。

• ベースライン run（engineSettings なし）: get-run の engineVersion は 26.04.0（nextflow.config の指定どおり）
• オーバーライド run（engineVersion を 24.10.8 に指定）: get-run の engineVersion が 24.10.8 に変わる。engineSettings にも指定値がそのまま返る

実行時にバージョン指定の何が嬉しいのか？

これまで特定の Nextflow バージョンで run するには、nextflow.config の manifest.nextflowVersion を書き換えて再登録する必要がありました。前の記事で扱った手法です。

engineVersion による実行時のバージョン指定は、ソースコードを変えずにバージョンを切り替えられます。公式ドキュメントは engineSettings を次のように説明しています。

For Nextflow v26.04.0 (and selected keys on earlier versions), you can pass an engineSettings map in the StartRun request to control engine behavior without modifying your workflow.

出典: Start a run in HealthOmics - Specify engine settings

つまり、嬉しいことは本番ワークフローを検証済みバージョンに固定したまま、同じワークフロー定義で新バージョンの挙動を並行テストできることです。

engineSettings とは

engineSettings は StartRun API でエンジン動作を制御するマップ形式のパラメータです（CLI では --engine-settings '{...}'）。nextflow.config を書き換えずにバージョンやパーサの設定を上書きできます。

参考: Start a run in HealthOmics - AWS HealthOmics

今回の構成

再利用する既存リソース

環境構築は前の記事で構築済みです。これらのリソースをそのまま流用します。

ベースライン run

まず engineSettings を渡さずに run し、nextflow.config に書いたバージョンがそのまま使われることを確認します。

既存環境とワークフローの確認

ワークフローが ACTIVE であることと、S3・サービスロールの存在を確認します。

aws omics get-workflow --id 7635166 --region us-east-1 --query 'status'
aws s3 ls s3://healthomics-nf2604-verify-<account-id>/ --region us-east-1
aws iam get-role --role-name healthomics-nf2604-service-role --query 'Role.Arn'

ACTIVE
                           PRE runs/
arn:aws:iam::<account-id>:role/healthomics-nf2604-service-role

start-run（engineSettings なし）

aws omics start-run \
  --workflow-id 7635166 \
  --role-arn arn:aws:iam::<account-id>:role/healthomics-nf2604-service-role \
  --name "pin-baseline-2604" \
  --output-uri s3://healthomics-nf2604-verify-<account-id>/pinning/ \
  --storage-type DYNAMIC \
  --region us-east-1

{
    "arn": "arn:aws:omics:us-east-1:<account-id>:run/3469563",
    "id": "3469563",
    "status": "PENDING",
    "uuid": "d8cf50f9-5d17-5963-8ed4-b9e7ce4c5918",
    "runOutputUri": "s3://healthomics-nf2604-verify-<account-id>/pinning/3469563",
    "networkingMode": "RESTRICTED"
}

run ID 3469563 が COMPLETED になるまで待ちます。

aws omics wait run-completed --id 3469563 --region us-east-1

DYNAMIC ストレージのため約 4〜8 分で完了しました。STATIC はプロビジョニング時間が加わるため、バージョン比較のような複数 run では DYNAMIC の方が待ち時間を抑えられます。

get-run で engineVersion を確認

ベースライン run が COMPLETED になったら、使われた Nextflow バージョンを確認します。engineSettings を渡していないため、engineSettings フィールドは null でした。engineVersion には nextflow.config から検出された 26.04.0 が返ります。

aws omics get-run --id 3469563 --region us-east-1 \
  --query '{status:status,engineVersion:engineVersion,engineSettings:engineSettings}'

{
    "status": "COMPLETED",
+    "engineVersion": "26.04.0",
    "engineSettings": null
}

engineVersion=24.10.8 でオーバーライド run

同じワークフロー（id 7635166）をそのまま使い、--engine-settings でバージョンを 24.10.8 に上書きして run します。

start-run（--engine-settings 付き）

aws omics start-run \
  --workflow-id 7635166 \
  --role-arn arn:aws:iam::<account-id>:role/healthomics-nf2604-service-role \
  --name "pin-override-2410" \
  --output-uri s3://healthomics-nf2604-verify-<account-id>/pinning/ \
  --storage-type DYNAMIC \
  --engine-settings '{"engineVersion":"24.10.8"}' \
  --region us-east-1

{
    "arn": "arn:aws:omics:us-east-1:<account-id>:run/4768546",
    "id": "4768546",
    "status": "PENDING",
    "uuid": "c8cf50f9-7323-9f10-d93a-67133aad23c7",
    "runOutputUri": "s3://healthomics-nf2604-verify-<account-id>/pinning/4768546",
    "networkingMode": "RESTRICTED"
}

get-run で engineVersion と engineSettings を確認

オーバーライド run も同様に待ちます。

aws omics wait run-completed --id 4768546 --region us-east-1

COMPLETED になったら、engineVersion と engineSettings を確認します。engineSettings に指定した {"engineVersion":"24.10.8"} がそのまま返り、engineVersion も 24.10.8 に変わっています。

aws omics get-run --id 4768546 --region us-east-1 \
  --query '{status:status,engineVersion:engineVersion,engineSettings:engineSettings}'

{
    "status": "COMPLETED",
+    "engineVersion": "24.10.8",
+    "engineSettings": {
+        "engineVersion": "24.10.8"
    }
}

S3 出力の確認

両 run の hello.txt が出力されていることを確認します。出力パスは <output-uri>/<run-id>/pubdir/hello.txt です（run の UUID は含まれません）。ワークフローは変えていないので、出力内容はどちらの run も同じです。

aws s3 cp s3://healthomics-nf2604-verify-<account-id>/pinning/3469563/pubdir/hello.txt - --region us-east-1
aws s3 cp s3://healthomics-nf2604-verify-<account-id>/pinning/4768546/pubdir/hello.txt - --region us-east-1

Hello World from AWS HealthOmics with Nextflow 26.04
Hello World from AWS HealthOmics with Nextflow 26.04

engine.log でバージョンを裏取りする

get-run の engineVersion に加えて、engine.log のバナーでも動作バージョンを確認できます。

aws s3 cp s3://healthomics-nf2604-verify-<account-id>/pinning/3469563/logs/engine.log - --region us-east-1 | grep -i version:
aws s3 cp s3://healthomics-nf2604-verify-<account-id>/pinning/4768546/logs/engine.log - --region us-east-1 | grep -i version:

# ベースライン run
  Version: 26.04.0 build 0
# オーバーライド run
  Version: 24.10.8 build 5940

ダウングレード時の注意

engineVersion で古いバージョンを指定すると、構文は v1（レガシー）パーサで解釈されます。strict（v2）パーサは v26.04.0 以降にしか存在しないためです。なお v26.04.0 でも syntaxVersion を v1 に設定すれば v1 パーサで実行できます。

今回の main.nf は record types などの v2 固有構文を使わない標準的な DSL2 で書かれているため、24.10.8 でもパースエラーなく完了しました。engine.log にも DSL2 - revision と出ています。

v2 固有構文に依存するワークフローを 24.10.8 や 25.10.0 へ下げると、パーサの違いで動かなくなります。

まとめ

StartRun API の engineSettings.engineVersion を使うと、nextflow.config を変更せずにエンジンバージョンを実行時に固定できます。

• --engine-settings '{"engineVersion":"24.10.8"}' を追加するだけで、ソースコードはそのままでバージョンをオーバーライドできる
• engineVersion は全サポートバージョンで有効
  • syntaxVersion など他のキーは v26.04.0 以降が対象
• v2 固有構文に依存するワークフローを古いバージョンへ下げる場合は構文の互換性に注意

おわりに

HealthOmics は実行時のバージョン制御まわりが少しずつ充実してきました。東京リージョンで使えないため、私の観測範囲ですとなかなか導入が進まないです。東京リージョンへの展開お待ちしております。

参考

• Start a run in HealthOmics - AWS HealthOmics User Guide
• Version support for HealthOmics workflow definition languages
• AWS HealthOmics で実行時の Nextflow バージョンの固定がサポートされるようになりました