AWS HealthOmics에서 nf-core/sarek 3.9.0 실행하기
이 가이드는 HealthOmics MCP server와 AWS CLI를 사용하여
nf-core/sarek 3.9.0 germline/somatic 변이 분석 파이프라인을
AWS HealthOmics에 등록하고 성공적으로 실행하는 데 필요한 모든 내용을 담고 있습니다.
이 문서는 COMPLETED 상태로 깔끔하게 완료된 end-to-end 실행 경험을 바탕으로 작성되었으며,
그 과정에서 만난 다섯 가지 블로커 각각의 근본 원인과 정확한 해결책을 다룹니다.
아래의 모든 결과는 us-west-2의 실제 실행에서 검증되었습니다. 계정 ID, VPC/서브넷/보안 그룹
ID, private 엔드포인트는 플레이스홀더로 대체되었습니다:
| Placeholder | 의미 |
|---|---|
<ACCOUNT_ID> |
12자리 AWS 계정 ID |
<REGION> |
실행하는 AWS 리전 (이 가이드에서는 us-west-2 사용) |
<OUTPUT_BUCKET> |
<REGION>에 소유한 S3 버킷 (정의, 입력, 출력용) |
<OMICS_RUN_ROLE_ARN> |
HealthOmics가 실행 시 assume하는 IAM 역할 |
<VPC_CONFIG_NAME> |
HealthOmics VPC 네트워킹 구성 (ACTIVE) |
<ECR> |
<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com |
TL;DR — 실제로 필요한 것
sarek 3.9.0은 nextflowVersion = '!>=25.10.2'를 고정하므로 HealthOmics는 Nextflow 26.04.0
엔진에서 실행됩니다. 깔끔한 실행을 위해서는 파이프라인 문서만으로는 파악하기 어려운 다섯 가지
독립적인 문제를 해결해야 했습니다:
| # | 증상 | 근본 원인 | 해결책 |
|---|---|---|---|
| 1 | 어떤 태스크도 실행되기 전에 ValidationException ... StartRun: S3 object not found 발생 |
nf-schema가 기본 snpeff_cache = 's3://annotation-cache/...' 파라미터(스키마 format: directory-path)를 stat하여 검증할 때 HealthOmics S3 프로바이더가 non-object 키에서 예외를 던짐 |
validate_params = false로 실행 |
| 2 | 컨테이너 해석 시 ECR_PERMISSION_ERROR 발생 |
Wave 이미지가 수동으로 생성된 ECR 레포지토리에 미러링되었으며, 이 레포지토리에는 omics.amazonaws.com의 pull 접근을 허용하는 레포지토리 정책이 없음 |
미러링된 모든 레포지토리에 set-repository-policy 적용 |
| 3 | 2개 태스크 후 INVALID_TASK_RESOURCE_VALUE 발생 |
BWAMEM1_INDEX가 memory { 6.B * fasta.size() }를 요청할 때 작은 테스트 게놈에서 1 GiB 미만의 값이 나와 HealthOmics 최솟값 기준에 미달 |
conf/healthomics.config에서 리소스 하한값 설정 |
| 4 | 최종 태스크에서 multiqc: command not found 발생 |
sarek의 MULTIQC 컨테이너는 Seqera Wave "pixi" 이미지로, 바이너리가 이미지 ENTRYPOINT를 통해서만 PATH에 추가되지만 HealthOmics는 이를 무시 |
MULTIQC를 quay.io/biocontainers 이미지로 오버라이드 |
| — | (3.9.0에서는 해당 없음) 설정 파싱 | 3.9.0은 엄격한 v2 파서 기반으로 작성됨 (26.04.0의 기본값) | syntaxVersion=v1 불필요 |
그리고 구조적인 사실 하나: ECR pull-through cache는 community.wave.seqera.io를 지원하지 않습니다.
sarek은 컨테이너의 절반가량을 이곳에서 가져오므로, 해당 이미지들은 수동으로 private ECR에 미러링해야 합니다.
최종 검증 결과: 23/23 태스크 COMPLETED 완료, Strelka VCF, 재보정된 CRAM, 전체 MultiQC 리포트 생성.
0. 사전 요구사항
| 요구사항 | 비고 |
|---|---|
| AWS 계정 + HealthOmics 지원 리전 | 이 가이드에서는 us-west-2 사용 |
| AWS CLI v2, 최신 버전 | omics start-run --engine-settings를 지원해야 함 |
| Docker 실행 중, 여유 디스크 ~50 GB | Seqera Wave 이미지를 ECR에 미러링하기 위해 필요 |
git, zip |
파이프라인 클론 및 패키징에 필요 |
HealthOmics 실행 역할 (<OMICS_RUN_ROLE_ARN>) |
omics.amazonaws.com 신뢰; 권한은 §0.1 참조 |
VPC 네트워킹 구성 (<VPC_CONFIG_NAME>, ACTIVE) |
private 서브넷 + NAT (GitHub에 호스팅된 테스트 데이터를 가져오기 위한 인터넷 출구 필요) |
AWSServiceRoleForHealthOmics SLR |
최초 omics 사용 시 자동 생성 |
0.1 실행 역할 권한
HealthOmics가 실행 시 assume하는 역할에는 다음 권한이 필요합니다:
- S3: 워크플로우 정의 및 입력 읽기, 출력 위치 읽기+쓰기.
- CloudWatch Logs:
/aws/omics/*에 쓰기. - ECR:
ecr:GetAuthorizationToken,ecr:BatchCheckLayerAvailability,ecr:GetDownloadUrlForLayer,ecr:BatchGetImage(캐시/미러링된 이미지용).
참고: HealthOmics는 **서비스 주체(service principal)**로서 각 ECR 레포지토리의 리소스 정책을 통해 컨테이너 이미지를 pull합니다 — 실행 역할만으로는 충분하지 않습니다. 이 차이가 블로커 #2(§4)의 근본 원인입니다.
0.2 HealthOmics MCP 서버 구성
MCP 서버는 에이전트 기반 워크플로우를 위해 HealthOmics API를 래핑합니다. 온보딩 시 다음과 같은 소규모 설정 파일이 생성됩니다:
# .healthomics/config.toml
omics_iam_role = "<OMICS_RUN_ROLE_ARN>"
run_output_uri = "s3://<OUTPUT_BUCKET>/healthomics-outputs/"
run_storage_type = "DYNAMIC"
MCP 서버는 uvx awslabs.aws-healthomics-mcp-server@latest로 실행됩니다. 워크플로우
생성(CreateAHOWorkflow, CreateAHOWorkflowVersion), 실행(StartAHORun, GetAHORun,
ListAHORunTasks), 진단(DiagnoseAHORunFailure), 컨테이너/ECR 헬퍼
(CreatePullThroughCacheForHealthOmics, CreateContainerRegistryMap,
ValidateHealthOmicsECRConfig) 도구를 제공합니다.
사전에 알아야 할 MCP 제한 사항:
StartAHORun도구에는engineSettings인수가 없습니다.-profile또는syntaxVersion을 전달하려면 AWS CLI(aws omics start-run --engine-settings)를 사용하세요. 나머지는 모두 MCP 도구를 통해 처리할 수 있습니다.
1. HealthOmics를 시작하기 전에 파이프라인 이해하기
sarek 3.9.0에 관한 몇 가지 사실이 이후의 모든 결정에 영향을 미칩니다. 기억에 의존하지 말고 소스에서 직접 확인하세요:
# Manifest: engine pin + version
curl -sSL https://raw.githubusercontent.com/nf-core/sarek/3.9.0/nextflow.config \
| grep -E "nextflowVersion|version *="
# -> nextflowVersion = '!>=25.10.2' version = '3.9.0'
# Container registry defaults
curl -sSL https://raw.githubusercontent.com/nf-core/sarek/3.9.0/nextflow.config \
| grep -E "docker.registry"
# -> docker.registry = 'quay.io' (so bare `biocontainers/x` means quay.io/biocontainers/x)
핵심 사항:
- 엔진:
!>=25.10.2는 강제 버전 고정입니다. HealthOmics가 지원하는 버전 (22.04.01 / 23.10.0 / 24.10.8 / 25.10.0 / 26.04.0) 중 26.04.0만 조건을 충족합니다. 26.04.0은 엄격한 (v2) 문법 파서를 기본값으로 사용합니다. - v2 파서 호환성: sarek 3.8.1(
if () {}블록 안에withName셀렉터를 중첩시켜syntaxVersion=v1이 필요했음)과 달리, sarek 3.9.0의 설정은 v2 호환 — 229개의withName셀렉터가 모두process {}최상위에 있으며if ()는 클로저(ext.args = { ... }) 내부에만 등장합니다.syntaxVersion오버라이드가 필요하지 않습니다. - 컨테이너는 두 레지스트리에 걸쳐 있습니다:
quay.io/biocontainers/*— 익명 pull 가능; ECR pull-through cache를 통해 사용 가능.community.wave.seqera.io/library/*(Seqera Wave) — ~27개 이미지; ECR PTC는 이 업스트림을 지원하지 않으므로, private ECR에 수동으로 미러링해야 합니다.
- 테스트 프로파일은 HTTPS를 통해 소규모 공개 데이터를 사용합니다:
conf/test.config는genome = 'testdata.nf-core.sarek'을 설정하고input/igenomes_base를https://raw.githubusercontent.com/nf-core/test-datasets/...로 지정합니다. 이는 크로스 리전 iGenomes(s3://ngi-igenomes, eu-west-1) 문제를 의도적으로 피하지만,raw.githubusercontent.com에 접근하려면 여전히 NAT egress가 있는 VPC 네트워킹이 필요합니다.
2. 컨테이너 전략 (가장 어려운 부분)
HealthOmics는 동일 계정 및 리전의 private ECR에서만 태스크 컨테이너를 pull합니다. sarek의 컨테이너는 업스트림에 있으므로, 두 가지 방법으로 연결합니다.
2.1 quay.io/biocontainers → ECR pull-through cache
MCP 도구는 캐시 규칙을 생성하고 동시에 HealthOmics 권한(레지스트리 정책 + 레포지토리 생성 템플릿)을 한 번의 호출로 설정합니다:
CreatePullThroughCacheForHealthOmics(upstream_registry="quay", ecr_repository_prefix="quay")
이후 모든 quay.io/biocontainers/foo:tag는 <ECR>/quay/biocontainers/foo:tag에서 접근할 수
있으며, 캐시가 자동 생성한 레포지토리는 생성 템플릿에서 omics pull 정책을 자동 상속합니다.
2.2 community.wave.seqera.io → ECR에 수동 미러링
ECR pull-through cache는 community.wave.seqera.io를 거부합니다:
UnsupportedUpstreamRegistryException: The upstream registry URL
community.wave.seqera.io is invalid.
따라서 각 Wave 이미지를 Docker로 미러링합니다. 먼저 파이프라인이 참조하는 이미지를 정확히 열거하여 필요한 것만 미러링합니다:
git clone --depth 1 --branch 3.9.0 https://github.com/nf-core/sarek.git sarek-390
cd sarek-390
grep -rhoE "community\.wave\.seqera\.io/library/[^'\"]+" modules/ \
| grep -v '/data$' | sort -u > /tmp/wave_images.txt
wc -l /tmp/wave_images.txt # 27 references (25 distinct Docker images; see note below)
그런 다음 pull → retag → push 순서로 community.wave.seqera.io/library/...를
wave/library/...로 평탄화합니다:
REG="<ECR>"
aws ecr get-login-password --region <REGION> | docker login --username AWS --password-stdin "$REG"
while IFS= read -r SRC; do
REPO_PATH="wave/${SRC#community.wave.seqera.io/}" # wave/library/foo:tag
REPO_NAME="${REPO_PATH%%:*}"
DEST="$REG/$REPO_PATH"
aws ecr create-repository --repository-name "$REPO_NAME" --region <REGION> \
--image-tag-mutability MUTABLE 2>/dev/null || true
docker pull -q "$SRC" && docker tag "$SRC" "$DEST" && docker push -q "$DEST"
docker rmi "$SRC" "$DEST" >/dev/null 2>&1 || true
done < /tmp/wave_images.txt
미러링된 23개의 레포지토리(일부는 여러 태그 포함)는 다음과 같습니다:
wave/library/ascat_cancerit-allelecount wave/library/manta_python
wave/library/bbmap_pigz wave/library/multiqc
wave/library/bcftools wave/library/muse
wave/library/bcftools_htslib wave/library/sentieon
wave/library/bwa-mem2_htslib_samtools wave/library/snpeff
wave/library/bwa_htslib_samtools wave/library/varlociraptor
wave/library/coreutils_grep_gzip_lbzip2_pruned wave/library/vcflib
wave/library/ensembl-vep_perl-math-cdf_htslib wave/library/yte
wave/library/fastp wave/library/htslib
wave/library/fgbio wave/library/htslib_muse
wave/library/gatk4_gcnvkernel wave/library/htslib_snpsift
wave/library/gatk4_gcnvkernel_htslib_samtools
두 개의 Wave multiqc 태그는 Docker로 pull되지 않습니다 — 이는 Singularity SIF 아티팩트(
application/vnd.sylabs.sif.config.v1+json)이기 때문입니다. 예상된 동작으로, HealthOmics는 Docker/OCI 이미지를 실행하며 MULTIQC 모듈의 Docker 경로는 다른 태그를 사용합니다. SIF 태그는 건너뛰세요.
2.3 미러링된 레포지토리에 omics.amazonaws.com pull 접근 권한 부여 (블로커 #2)
이 부분이 미묘합니다. aws ecr create-repository로 생성한 레포지토리에는 레포지토리 정책이
없으므로, 이미지가 존재하고 실행 역할에 ECR 권한이 있더라도 HealthOmics 서비스 주체가 pull하지
못해 ECR_PERMISSION_ERROR로 실행이 실패합니다. (pull-through cache가 생성한 레포지토리는
생성 템플릿에서 이 정책을 자동으로 받지만, 수동 생성 레포지토리는 그렇지 않습니다.) 미러링된
모든 레포지토리에 동일한 정책을 적용합니다:
POLICY='{"Version":"2012-10-17","Statement":[{"Sid":"omics workflow access",
"Effect":"Allow","Principal":{"Service":"omics.amazonaws.com"},
"Action":["ecr:GetDownloadUrlForLayer","ecr:BatchGetImage","ecr:BatchCheckLayerAvailability"]}]}'
for R in $(aws ecr describe-repositories --region <REGION> \
--query 'repositories[?starts_with(repositoryName,`wave/`)].repositoryName' --output text); do
aws ecr set-repository-policy --repository-name "$R" --region <REGION> --policy-text "$POLICY"
done
2.4 컨테이너 레지스트리 맵
워크플로우는 HealthOmics에게 업스트림 이미지 참조를 ECR로 재작성하는 방법을 알려주는 맵이 필요합니다:
registryMappings— pull-through cache의 접두사 재작성(quay.io→quay).imageMappings— 미러링된 Wave 이미지에 대한 이미지별 명시적 재작성.
{
"registryMappings": [
{ "upstreamRegistryUrl": "quay.io", "ecrRepositoryPrefix": "quay" }
],
"imageMappings": [
{
"sourceImage": "community.wave.seqera.io/library/fastp:0.24.0--62c97b06e8447690",
"destinationImage": "<ECR>/wave/library/fastp:0.24.0--62c97b06e8447690"
}
// ... one entry per mirrored Wave image ...
]
}
registryMappings 부분은 MCP 도구 CreateContainerRegistryMap으로 발견된 pull-through cache에서
자동 생성할 수 있으며, 미러 목록에서 생성한 Wave imageMappings를 이어 붙이면 됩니다. ECR 구성은
언제든지 ValidateHealthOmicsECRConfig로 검증할 수 있습니다.
3. HealthOmics 호환성 설정
두 가지 파이프라인 동작이 HealthOmics와 호환되지 않으며, 워크플로우에 포함된 소규모 추가 설정
파일로 해결하는 것이 가장 좋습니다. conf/healthomics.config를 생성합니다:
/*
* HealthOmics compatibility overrides.
*
* 1) Resource floors: some nf-core modules compute memory from input size
* (e.g. BWA index: `6.B * fasta.size()`). Tiny test genomes yield < 1 GiB,
* which HealthOmics rejects (INVALID_TASK_RESOURCE_VALUE). Floor them.
*
* 2) MULTIQC container override: sarek's default MULTIQC container is a Seqera
* Wave "pixi" image whose binary lives in /opt/wave/.pixi/... and is put on
* PATH only by the image ENTRYPOINT (/shell-hook.sh). HealthOmics runs the
* task command directly and IGNORES ENTRYPOINT, so `multiqc` is not found.
* Use the standard biocontainers image (binary on /usr/local/bin), pulled
* via the quay.io ECR pull-through cache.
*/
process {
withName: '.*:BWAMEM1_INDEX' { memory = { 2.GB * task.attempt }; cpus = 2 }
withName: '.*:BWAMEM2_INDEX' { memory = { 6.GB }; cpus = 2 }
withName: '.*:DRAGMAP_HASHTABLE'{ memory = { 4.GB * task.attempt }; cpus = 2 }
withName: '.*:MULTIQC' {
container = 'quay.io/biocontainers/multiqc:1.35--pyhdfd78af_0'
}
}
nextflow.config에 한 줄을 추가하여 파이프라인에 연결합니다:
printf "\n// AWS HealthOmics resource floors + container overrides\nincludeConfig 'conf/healthomics.config'\n" >> nextflow.config
왜 이 두 가지인가
- 블로커 #3 — 리소스 하한값.
modules/nf-core/bwa/index/main.nf는memory { 6.B * fasta.size() }를 선언합니다. 작은 테스트 게놈(~수 KB)에서는 수 KB로 평가되어 HealthOmics가INVALID_TASK_RESOURCE_VALUE("... less than the minimum value of 1")로 1 GiB 미만을 요청하는 태스크를 거부합니다. 하한값 설정으로 요청이 유효해집니다. 이 패턴은 입력 크기 기반 메모리 수식이 있는 경우에도 동일하게 발생할 수 있습니다.- 블로커 #4 — MULTIQC 컨테이너. Wave "pixi" 이미지는
multiqc를/opt/wave/.pixi/envs/default/bin/multiqc에 배치하고,ENTRYPOINT(/bin/bash /shell-hook.sh)를 통해 환경을 활성화하고PATH에 추가합니다. HealthOmics는 컨테이너ENTRYPOINT를 무시하고 태스크 명령을 직접 실행하므로,PATH에 pixi 바이너리가 포함되지 않아multiqc: command not found가 발생합니다. biocontainers 이미지는multiqc를/usr/local/bin에 배치하므로 entrypoint 훅이 필요 없습니다. 이 문제는 다른 pixi 기반 Wave 이미지에도 동일하게 적용될 가능성이 높습니다 — Wave 이미지가 entrypoint 훅에 의존하는 경우 biocontainers 동등 이미지를 선호하세요.
4. 워크플로우 등록
파이프라인(conf/healthomics.config 포함)을 패키징하고 등록합니다. CodeConnection을 통해 Git
레포지토리에서 직접 등록하거나 S3 zip에서 등록할 수 있습니다. 이 가이드는 S3-zip 방식을 사용합니다
(Console OAuth 단계를 생략하고 나머지 인프라와 동일한 리전에 정의를 보관할 수 있음):
cd sarek-390
zip -qr /tmp/sarek-3.9.0.zip . -x "*.git*" ".git/*"
aws s3 cp /tmp/sarek-3.9.0.zip s3://<OUTPUT_BUCKET>/workflow-defs/sarek-3.9.0.zip --region <REGION>
그런 다음 MCP 도구 CreateAHOWorkflow로 워크플로우를 생성하며, 다음을 전달합니다:
definition_uri = s3://<OUTPUT_BUCKET>/workflow-defs/sarek-3.9.0.zipengine = NEXTFLOW,path_to_main = main.nf,storage_type = DYNAMICcontainer_registry_map = { ... }(§2.4 참조)- 파라미터 템플릿 (
optional세부 사항은 §5 참조)
GetAHOWorkflow로 워크플로우가 ACTIVE 상태에 도달하는지 확인합니다 — 이는 정의가 26.04.0에서
파싱되고 레지스트리 맵이 수락되었음을 검증합니다.
4.1 파라미터 템플릿 — -profile 사용 시 input/outdir을 optional로 설정
HealthOmics는 required 파라미터 템플릿 항목을 StartRun 시점에, Nextflow 실행 이전에
강제 확인합니다 — 프로파일이 값을 제공할 예정이더라도 마찬가지입니다. input이 required이고
-profile test에 의존한다면 StartRun이 실패합니다:
ValidationException: Missing workflow parameters: input
프로파일 기반 테스트 실행을 위해 템플릿에서 input과 outdir을 optional로 표시합니다.
최소한의 템플릿:
{
"input": { "description": "Samplesheet CSV (supplied by -profile test if omitted)", "optional": true },
"outdir": { "description": "Output dir — use /mnt/workflow/output/ on HealthOmics", "optional": true },
"genome": { "description": "iGenomes key", "optional": true },
"tools": { "description": "Variant callers, e.g. strelka", "optional": true },
"validate_params": { "description": "Enable/disable nf-schema param validation", "optional": true },
"snpeff_cache": { "description": "snpEff cache dir", "optional": true },
"vep_cache": { "description": "VEP cache dir", "optional": true }
}
5. 파이프라인 실행
5.1 깔끔한 방법 — engineSettings.profile
HealthOmics는 engineSettings.profile을 Nextflow에 -profile로 전달합니다. 이를 통해 sarek의
conf/test.config가 샘플시트, 게놈, 도구, 참조 기본 경로를 제공하므로 프로파일이 설정하지
않는 것만 전달하면 됩니다. MCP StartAHORun 도구에는 engineSettings 인수가 없으므로 CLI를
사용합니다:
aws omics start-run --region <REGION> \
--workflow-id <WORKFLOW_ID> --workflow-version-name v-profile \
--workflow-type PRIVATE --role-arn <OMICS_RUN_ROLE_ARN> \
--name sarek-3.9.0-profile-test \
--output-uri s3://<OUTPUT_BUCKET>/healthomics-outputs/sarek-3.9.0-profile/ \
--parameters '{"outdir":"/mnt/workflow/output/","validate_params":false}' \
--engine-settings '{"profile":"test"}' \
--storage-type DYNAMIC \
--networking-mode VPC --configuration-name <VPC_CONFIG_NAME>
두 파라미터는 여전히 명시적으로 지정해야 합니다(명시적 실행 파라미터가 프로파일 값을 오버라이드함):
outdir = /mnt/workflow/output/—test.config는outdir을 설정하지 않으며, HealthOmics에서는 이 로컬 export 경로여야만 합니다(s3://URI는 불가). HealthOmics는/mnt/workflow/output/아래에 작성된 모든 파일을 자동으로 실행의 S3 출력 위치로 export합니다. (태스크 출력에는publishDir '/mnt/workflow/pubdir'을 사용합니다.)validate_params = false— nf-schema의 즉각적인 파라미터 검증을 비활성화합니다. 이 검증은 기본snpeff_cache/vep_caches3://annotation-cache/...접두사를 stat 확인하여 블로커 #1을 유발합니다. (테스트는tools = strelka를 사용하므로 annotation cache가 필요하지 않습니다.)
5.2 명시적 방법 — test.config 파라미터를 직접 복제
프로파일에 의존하지 않으려 하거나(또는 템플릿에서 input을 required로 유지하는 경우), 테스트
프로파일 값을 직접 전달합니다. 더 장황하지만 동일한 결과입니다:
--parameters '{
"input":"s3://<OUTPUT_BUCKET>/sarek390-test/samplesheet.csv",
"outdir":"/mnt/workflow/output/",
"genome":"testdata.nf-core.sarek",
"tools":"strelka",
"split_fastq":0,
"validate_params":false,
"igenomes_base":"https://raw.githubusercontent.com/nf-core/test-datasets/modules/data/",
"modules_testdata_base_path":"https://raw.githubusercontent.com/nf-core/test-datasets/modules/data/",
"bcftools_annotations":"https://raw.githubusercontent.com/nf-core/test-datasets/modules/data/genomics/sarscov2/illumina/vcf/test2.vcf.gz",
"bcftools_annotations_tbi":"https://raw.githubusercontent.com/nf-core/test-datasets/modules/data/genomics/sarscov2/illumina/vcf/test2.vcf.gz.tbi"
}'
여기서 샘플시트는 tests/csv/3.0/fastq_single.csv(patient,sex,status,sample,lane,fastq_1,fastq_2
열)를 미러링하며 FASTQ URL은 공개 nf-core/test-datasets 레포지토리를 가리킵니다. HTTPS URL이므로
실행에는 여전히 VPC 네트워킹이 필요합니다.
5.3 모니터링
aws omics get-run --id <RUN_ID> --region <REGION> \
--query '{status:status,engineVersion:engineVersion,failureReason:failureReason}'
aws omics list-run-tasks --id <RUN_ID> --region <REGION> \
--query 'items[].{name:name,status:status}'
실패 시, MCP DiagnoseAHORunFailure 도구(또는 CloudWatch run/<id>/engine 로그 스트림)에서
실제 원인을 확인할 수 있습니다. failureReason은 일반적인(WORKFLOW_RUN_FAILED) 내용이며,
manifest 로그의 statusMessage와 첫 번째 비-SDK 스택 프레임이 실패한 태스크와 호출 위치를
정확히 가리킵니다.
6. 검증된 결과
두 실행 방식 모두 COMPLETED로 깔끔하게 완료됩니다:
| 실행 방식 | 엔진 | 태스크 | 결과 | 출력 오브젝트 수 |
|---|---|---|---|---|
| 명시적 파라미터 (§5.2) | 26.04.0 | 21/21 | COMPLETED |
349 |
profile=test (§5.1) |
26.04.0 | 23/23 | COMPLETED |
357 |
profile=test 실행은 conf/test.config가 추가 QC를 활성화하므로 몇 가지 태스크가 더 예약됩니다.
출력물(실행의 runOutputUri 아래)에는 다음이 포함됩니다:
variant_calling/strelka/test/test.strelka.variants.vcf.gz— 변이 호출 결과preprocessing/recalibrated/test/test.recal.cram— 정렬, 중복 표시, BQSR 재보정된 리드multiqc/multiqc_report.html— 통합 QC 리포트pipeline_info/— 실행 리포트, 타임라인, DAG, BCO 출처 매니페스트
성공적으로 실행된 태스크는 전체 파이프라인에 걸쳐 있습니다: BWAMEM1_INDEX, interval prep,
FASTQC, BWAMEM1_MEM, GATK4_MARKDUPLICATES, GATK4_BASERECALIBRATOR, GATK4_APPLYBQSR,
STRELKA_SINGLE, BCFTOOLS_STATS, VCFTOOLS_*, MOSDEPTH, SAMTOOLS_STATS, MULTIQC.
7. AWS 문서와의 교차 검증
AWS 가이드 Nextflow workflow definition specifics는 핵심 결정 사항을 뒷받침하며 알아둘 만한 운영 메모를 몇 가지 추가합니다:
- 플러그인은 사전 설치 및 고정됩니다. 26.04.0은
nf-schema@2.7.2,nf-core-utils@0.4.0,nf-prov@1.7.0,nf-fgbio@1.0.1을 제공합니다. "워크플로우 실행 중 추가 플러그인을 가져올 수 없습니다. HealthOmics는nextflow.config파일에 지정된 다른 플러그인 버전을 무시합니다." (이는nf-validation에 의존하는 구버전 sarek이 26.04.0에서 실패하는 이유이기도 합니다 — 해당 플러그인은 제공되지 않습니다.) params.outdir/ export./mnt/workflow/output/에 작성된 파일은 실행의 S3 출력으로 export됩니다. 태스크 출력에는publishDir '/mnt/workflow/pubdir'을 사용합니다. §5.1을 확인합니다.- 프로파일은 지원됩니다 —
engineSettings.profile을 통해, 워크플로우 zip 내부에 정의되어야 하며, 명시적 실행 파라미터가 프로파일 값을 오버라이드합니다. §5.1을 확인합니다. - v2 파서는 26.04.0의 기본값입니다.
engineSettings.syntaxVersion = "v1"으로 레거시로 되돌릴 수 있습니다. sarek 3.9.0에는 오버라이드가 필요 없습니다. - 격리된 네트워크. "HealthOmics 워크플로우는 외부 인터넷 접근이 없는 격리된 네트워크에서 실행됩니다." 태스크 노드는 VPC 구성의 NAT를 통해서만 인터넷에 접근할 수 있습니다 — 이것이 §0에서 GitHub에 호스팅된 테스트 데이터를 준비하기 위해 VPC 네트워킹이 필요한 이유입니다.
- 리포트에는 컨테이너 내
ps가 필요합니다.report/timeline/trace옵저버를 활성화하는 경우, 각 태스크 컨테이너에ps(procps/procps-ng)가 포함되어야 합니다. 그렇지 않으면 Nextflow가 태스크별 메트릭을 수집할 수 없습니다.container디렉티브가 없는 컨테이너는ps가 이미 포함된 HealthOmics 기본값을 사용합니다. - DAG 다이어그램 형식.
dag.file을 PDF/PNG/SVG로 사용하려면 Graphviz가 필요합니다(포함되지 않음)..dot파일로 폴백됩니다..html,.mmd,.dot를 권장합니다.
AWS Nextflow 페이지가 문서화하지 않은 한 가지 — 그리고 여기서 가장 어려운 두 가지 블로커 —
는 Seqera Wave 이미지의 컨테이너 처리입니다: ECR pull-through cache가 community.wave.seqera.io를
캐시할 수 없다는 점, 그리고 Wave "pixi" 이미지가 HealthOmics의 컨테이너 실행 방식과 호환되지
않는다는 점입니다. 이 사실들(§2.2 및 §3/블로커 #4)은 실험을 통해 확인되었습니다.
8. HealthOmics에서 모든 nf-core 파이프라인에 재사용 가능한 체크리스트
- 엔진 맞추기.
manifest.nextflowVersion을 확인합니다. 강제 고정으로 인해 26.04.0(엄격한 v2 파서)이 요구될 수 있습니다. 설정이 v2 호환인지 아니면syntaxVersion=v1이 필요한지 확인합니다. - 컨테이너.
quay.io/Docker Hub 이미지는 pull-through cache 사용; Seqera Wave 이미지는 private ECR에 미러링하고imageMappings추가; 그런 다음 수동으로 생성한 레포지토리에 레포지토리 정책 설정하여omics.amazonaws.com이 pull할 수 있도록 합니다. - 즉각적인 S3 검증 건너뛰기. 파이프라인 스키마의
directory-path기본값이s3://접두사를 가리키는 경우validate_params=false로 실행합니다. - 리소스 하한값 설정. CPU/메모리가 입력 크기에서 계산되어 1-GiB/1-CPU 최솟값 이하로 떨어질
수 있는 태스크에 대해
conf/healthomics.config를 추가합니다. - ENTRYPOINT 의존 컨테이너 수정. HealthOmics가
ENTRYPOINT를 무시하므로, Wave "pixi"(또는 entrypoint 훅을 사용하는 이미지)를 biocontainers 동등 이미지로 오버라이드합니다. outdir=/mnt/workflow/output/—s3://URI는 절대 사용하지 않습니다.- 저렴하게 테스트합니다.
engineSettings.profile=test(템플릿에서input/outdir을 optional로 표시)와 GitHub에 호스팅된 테스트 데이터용 VPC 네트워킹을 조합하는 것을 권장합니다.
9. 참고 자료
- nf-core/sarek 3.9.0
- HealthOmics — Nextflow workflow definition specifics
- HealthOmics — Nextflow version support
- HealthOmics — engine settings (profile / syntaxVersion / engineVersion)
- HealthOmics — VPC networking
- HealthOmics — ECR pull-through cache for workflows
- AWS HealthOmics MCP server
- nf-schema plugin
- Seqera strict (v2) syntax
No comments to display
No comments to display