# ADR: Nextflow Profiles no HealthOmics — Separação de Configuração e Lógica

O AWS HealthOmics passou a suportar Nextflow profiles, permitindo ativar configurações predefinidas em tempo de execução sem alterar o código-fonte do workflow. Esta análise examina a decisão arquitetural por trás dessa separação de concerns, seus trade-offs reais e as consequências operacionais para equipes que rodam pipelines bioinformáticos em escala.

- URL: https://fernando.moretes.com/blog/adr-nextflow-profiles-no-healthomics-separacao-de-configuracao-e-logic-aws-healthom

- Markdown: https://fernando.moretes.com/blog/adr-nextflow-profiles-no-healthomics-separacao-de-configuracao-e-logic-aws-healthom/article.md?lang=pt

- Published: 2026-06-23T14:56:59.334Z

- Category: AWS & Cloud

- Tags: healthomics, nextflow, bioinformatics, workflow, configuration-management, nf-core, hipaa, aws

- Reading time: 9 min

- Source: [AWS HealthOmics now supports Nextflow profiles](https://aws.amazon.com/about-aws/whats-new/2026/06/aws-healthomics-nextflow-profiles/)

---

Quando configuração e lógica vivem no mesmo arquivo, qualquer promoção de dev para prod vira um risco de regressão. O suporte a Nextflow profiles no AWS HealthOmics resolve exatamente esse problema — e a decisão de como estruturar essa separação tem consequências que vão muito além da conveniência operacional.

## Contexto e Forças: O Problema de Configuração em Pipelines Bioinformáticos

Pipelines bioinformáticos têm uma característica que os distingue de workloads de propósito geral: o mesmo código precisa rodar corretamente em contextos radicalmente diferentes. Um pipeline de variant calling que processa 30x WGS em produção pode precisar rodar com 2 CPUs e 8 GB de RAM em desenvolvimento para validação rápida, e com 64 vCPUs e 256 GB em produção para cumprir SLAs clínicos. Antes do suporte a profiles, a abordagem mais comum era manter arquivos `nextflow.config` separados por ambiente ou usar variáveis de ambiente com lógica condicional embutida no próprio código do workflow — ambas as abordagens violam o princípio de separação de concerns e introduzem drift entre ambientes.

No contexto do AWS HealthOmics, esse problema é amplificado por três forças específicas. Primeira: o serviço é HIPAA-eligible, o que significa que qualquer alteração em arquivos de workflow precisa passar por controles de auditoria — modificar `nextflow.config` para trocar de ambiente implica um artefato de workflow diferente, com hash diferente, exigindo re-validação. Segunda: workflows nf-core — que representam a grande maioria dos pipelines adotados em produção no setor — já vêm com profiles institucionais e de plataforma embutidos (`test`, `test_full`, `docker`, `singularity`, `awsbatch`), mas sem suporte nativo a profiles no HealthOmics, esses profiles eram ignorados ou exigiam adaptações manuais. Terceira: equipes de bioinformática raramente têm um SRE dedicado; a complexidade de manter múltiplas definições de workflow para o mesmo pipeline é um custo operacional real que se acumula com cada novo pipeline incorporado ao portfólio.

## A Decisão Arquitetural: O Que Realmente Mudou

A decisão central aqui não é sobre Nextflow profiles em si — essa é uma feature da ferramenta que existe há anos. A decisão é sobre **onde a separação de configuração e lógica deve ocorrer na cadeia de execução do HealthOmics**. Antes dessa mudança, o HealthOmics tratava o workflow como um artefato imutável e completo: tudo que precisava variar entre execuções tinha que ser passado como parâmetros de input (`--param valor`) ou estar embutido no código. Isso funcionava para parâmetros de negócio (qual arquivo de referência usar, qual sample processar), mas era inadequado para configurações de plataforma (limites de CPU/memória por processo, estratégias de retry, configurações de executor).

Com o suporte a profiles, o HealthOmics agora aceita um campo `engineOptions` na API de start-run que permite especificar um ou mais profiles pelo nome: `-profile test,aws`. Isso significa que o artefato de workflow registrado no HealthOmics Workflow Registry permanece imutável — o mesmo ARN, o mesmo hash SHA-256 — enquanto o comportamento de execução varia pelo profile selecionado em tempo de run. Do ponto de vista de auditoria HIPAA, isso é significativo: você pode demonstrar que o código científico não foi alterado entre execuções, enquanto as configurações de plataforma variam de forma controlada e rastreável através dos parâmetros de run.

A implicação de design mais importante é que profiles são resolvidos em tempo de execução pelo motor Nextflow dentro do ambiente gerenciado do HealthOmics. Isso significa que o arquivo `nextflow.config` dentro do artefato do workflow precisa definir os profiles antecipadamente — você não pode injetar um profile que não existe no artefato. A flexibilidade é real, mas é delimitada pelo que foi definido no momento do registro do workflow.

## Opções Consideradas para Separação de Configuração em HealthOmics

### Opção A: Múltiplas Definições de Workflow por Ambiente

**Pros**
- Isolamento completo entre ambientes; sem risco de configuração errada em prod
- Cada artefato é autocontido e auditável de forma independente

**Cons**
- Drift entre definições é inevitável; qualquer fix precisa ser aplicado em N artefatos
- Custo operacional alto: re-registro, re-validação e re-teste para cada promoção
- Viola o princípio DRY; aumenta a superfície de erro humano

**Verdict:** Rejeitada — custo operacional insustentável em portfólios com 10+ pipelines

### Opção B: Parâmetros de Input para Configurações de Plataforma

**Pros**
- Funciona com a API atual do HealthOmics sem modificações
- Rastreável via parâmetros de run no CloudWatch e HealthOmics Run History

**Cons**
- Mistura semântica: parâmetros científicos e de plataforma no mesmo namespace
- Workflows nf-core não foram projetados para receber configurações de executor via params
- Não resolve o problema de resource limits por processo — requer lógica condicional no DSL

**Verdict:** Parcialmente adequada para parâmetros de negócio; inadequada para configurações de executor

### Opção C: Nextflow Profiles via engineOptions (Decisão Adotada)

**Pros**
- Artefato de workflow permanece imutável; separação limpa de concerns
- Compatibilidade nativa com nf-core e profiles institucionais existentes
- Suporte a múltiplos profiles compostos (-profile test,aws) para flexibilidade máxima
- Rastreabilidade via engineOptions no run record; auditável para HIPAA

**Cons**
- Profiles precisam estar definidos no artefato registrado; sem injeção dinâmica
- Adicionar um novo profile requer re-registro do workflow (novo ARN ou nova versão)
- Complexidade de composição: ordem de profiles importa e pode causar sobrescrita silenciosa

**Verdict:** Adotada — melhor equilíbrio entre imutabilidade de artefato, auditabilidade e flexibilidade operacional

## Ciclo de Vida de Workflow com Nextflow Profiles no HealthOmics

Separação entre artefato imutável (registro) e configuração variável (profile selecionado em run time). O mesmo ARN de workflow serve dev, staging e prod via profiles distintos.

### 🔧 CI/CD — Build & Register

- Source Repo nextflow.config (profiles defined) (ci)
- CodePipeline workflow bundle validation (ci)
- HealthOmics Workflow Registry (immutable ARN + SHA-256) (storage)

### 🧬 Runtime — Profile Selection

- Orchestrator (Step Functions / CLI) startRun + engineOptions (compute)
- Profile: test 2 vCPU / 8 GB fast iteration (edge)
- Profile: prod,aws 64 vCPU / 256 GB clinical SLA (compute)
- HealthOmics Managed Run (Nextflow engine) (compute)

### 💾 Data & Storage

- S3 Input (FASTQ / BAM) SSE-KMS (storage)
- S3 Output (VCF / reports) SSE-KMS (storage)

### 🔍 Observability

- CloudWatch Run logs + metrics engineoptions captured (security)

### Fluxos

- repo -> codepipeline: bundle + config
- codepipeline -> registry: registerWorkflow
- caller -> dev_profile: -profile test
- caller -> prod_profile: -profile prod,aws
- dev_profile -> omics_run: startRun (dev)
- prod_profile -> omics_run: startRun (prod)
- registry -> omics_run: mesmo ARN
- omics_run -> s3_input: lê dados
- omics_run -> s3_output: escreve resultados
- omics_run -> cloudwatch: logs + engineOptions

## Consequências Operacionais: O Que Muda no Dia a Dia de uma Equipe de Bioinformática

A consequência mais imediata é a eliminação de uma classe inteira de erros humanos: a modificação acidental de parâmetros de produção durante edições de desenvolvimento. Em equipes que eu observei, esse tipo de erro — um `maxMemory = 256.GB` que sobrescreve o limite de dev de `8.GB` porque alguém editou o arquivo errado — é responsável por uma fração significativa dos incidentes de run failure no HealthOmics. Com profiles, o arquivo de configuração de produção nunca é tocado durante o desenvolvimento.

A segunda consequência é sobre **portabilidade de workflows nf-core**. Pipelines como `nf-core/sarek`, `nf-core/rnaseq` e `nf-core/viralrecon` já incluem profiles como `test` (dataset mínimo para CI), `test_full` (dataset completo para validação) e profiles de plataforma como `awsbatch`. Com o suporte nativo no HealthOmics, equipes podem agora registrar esses workflows sem modificação e selecionar o profile `test` para validação de CI/CD e o profile de produção para runs clínicos — usando o mesmo artefato registrado. Isso reduz o tempo de onboarding de um novo pipeline nf-core de dias para horas.

A terceira consequência, menos óbvia, é sobre **custo**. Profiles de desenvolvimento com limites menores de CPU e memória significam que runs de validação consomem menos recursos gerenciados do HealthOmics. Considerando que o HealthOmics cobra por tempo de run e recursos alocados, a capacidade de executar validações rápidas com o profile `test` — que tipicamente usa datasets sintéticos de 1-2 GB em vez dos 100-300 GB de um WGS completo — pode representar uma redução de 40-60% no custo de runs de CI/CD, dependendo da frequência de execução.

## Design para Auditabilidade HIPAA: Profiles como Evidência de Controle

Em ambientes HIPAA, a rastreabilidade de cada execução de workflow é um requisito, não uma conveniência. O modelo anterior — onde configurações de ambiente eram embutidas no artefato ou passadas de forma ad hoc — criava lacunas de auditoria: era difícil demonstrar que um run específico usou as configurações corretas sem inspecionar o artefato completo.

Com profiles, o campo `engineOptions` é capturado no run record do HealthOmics e propagado para os logs do CloudWatch. Isso significa que para cada run, você tem: (1) o ARN do workflow com seu hash SHA-256, que identifica unicamente o código científico; (2) os parâmetros de input, que identificam os dados processados; e (3) o `engineOptions` com os profiles selecionados, que identifica a configuração de plataforma. Esses três elementos juntos formam uma evidência de controle completa para auditoria.

Para maximizar essa rastreabilidade em um ambiente de grau clínico, recomendo estruturar o Step Functions state machine que orquestra os runs do HealthOmics para incluir o profile selecionado como um atributo de execução explícito, não apenas passá-lo no `engineOptions`. Isso permite queries no CloudWatch Logs Insights como `fields @timestamp, workflowId, selectedProfile, runStatus | filter selectedProfile = 'prod' | stats count() by runStatus` para auditorias rápidas. Adicionalmente, políticas IAM com condições no `omics:engineOptions` podem ser usadas para restringir quais roles podem iniciar runs com o profile `prod` — um controle de separação de ambientes que vai além do que era possível antes.

> **Consequências e Modos de Falha que Você Precisa Conhecer:** **1. Sobrescrita silenciosa em composição de profiles:** Quando você especifica `-profile test,aws`, o Nextflow aplica os profiles em ordem da esquerda para a direita, com o último vencendo em caso de conflito. Se o profile `aws` define `process.memory = '16 GB'` e o profile `test` define `process.memory = '4 GB'`, a ordem `-profile aws,test` resultará em 4 GB — o oposto do esperado para um run de produção que acidentalmente incluiu `test`. Não existe warning explícito do motor; o run simplesmente executa com a configuração sobrescrita.

**2. Profile inexistente causa falha silenciosa ou erro tardio:** Se você especificar um profile que não existe no `nextflow.config` do artefato registrado, o comportamento depende da versão do Nextflow: versões mais antigas ignoram silenciosamente o profile inexistente; versões mais recentes emitem um warning mas continuam a execução. Em ambos os casos, você não recebe o comportamento esperado sem um erro claro. Valide profiles existentes como parte do seu pipeline de CI antes do registro.

**3. Profiles não substituem parâmetros de input:** Configurações definidas via `params` no `nextflow.config` dentro de um profile têm precedência menor do que parâmetros passados via `--param` na linha de comando ou no campo `parameters` da API. Isso pode causar confusão quando um profile de produção define `params.genome = 'GRCh38'` mas o caller passa `--genome GRCh37` — o profile é ignorado para esse parâmetro específico.

**4. Limite de tamanho de engineOptions:** A API do HealthOmics tem limites de tamanho para campos de string. Composições longas de profiles com argumentos adicionais podem aproximar-se desse limite. Monitore o tamanho do `engineOptions` em runs automatizados.

## Integração com o Ecossistema AWS: Step Functions, IAM e Observabilidade

A feature de profiles não existe no vácuo — ela precisa ser integrada ao ecossistema de orquestração e governança que envolve o HealthOmics. A integração mais natural é com o Step Functions, que tipicamente serve como o orquestrador de workflows bioinformáticos em produção, gerenciando sequências de runs, dependências entre pipelines e tratamento de erros.

Na prática, recomendo modelar o profile como uma variável de entrada explícita no state machine do Step Functions, não como um valor hardcoded. O estado `StartHealthOmicsRun` deve receber `$.profile` como input e construir o `engineOptions` dinamicamente: `"engineOptions": { "nextflow": { "profile": "$.profile" } }`. Isso permite que o mesmo state machine sirva dev e prod, com o profile sendo determinado pelo evento que dispara a execução — um evento de CI passa `test`, um evento de produção clínica passa `prod,aws`.

Do ponto de vista de IAM, a separação de profiles abre uma oportunidade de controle que não existia antes. Você pode criar uma política de IAM que usa condições `StringLike` no `omics:engineOptions` para restringir quais roles podem iniciar runs com profiles de produção. Por exemplo, uma role de CI/CD pode ser limitada a iniciar apenas runs com `-profile test` ou `-profile test_full`, enquanto a role de execução clínica tem permissão para `-profile prod,aws`. Isso implementa separação de ambientes no plano de controle, não apenas no plano de dados.

Para observabilidade, o sinal mais valioso é correlacionar o profile selecionado com as métricas de custo e duração do run. Uma query no CloudWatch Logs Insights que agrupa `runDuration` e `estimatedCost` por `selectedProfile` permite identificar rapidamente se runs de desenvolvimento estão inadvertidamente usando profiles de produção — um sinal de alerta precoce para tanto desperdício de custo quanto potencial vazamento de configuração.

## Anti-Padrões a Evitar com Nextflow Profiles no HealthOmics

- **Profile como substituto de versionamento:** Usar profiles para gerenciar versões de algoritmo (ex: `profile_v1`, `profile_v2`) em vez de versões de workflow. Profiles são para configuração de plataforma, não para lógica científica. Lógica diferente = artefato diferente.
- **Credenciais ou segredos em profiles:** Nunca colocar ARNs de KMS keys, endpoints de banco de dados ou qualquer dado sensível diretamente em profiles no `nextflow.config`. Use SSM Parameter Store ou Secrets Manager e referencie via variáveis de ambiente no processo.
- **Profile único para todos os processos:** Definir um profile monolítico que aplica os mesmos limites de CPU/memória a todos os processos do workflow. Processos de alinhamento (BWA-MEM2) têm perfis de recurso radicalmente diferentes de processos de variant calling (GATK HaplotypeCaller). Use `withName` ou `withLabel` dentro dos profiles para granularidade por processo.
- **Ignorar a ordem de composição de profiles:** Assumir que a ordem dos profiles em `-profile a,b,c` não importa. Sempre documente a ordem esperada e inclua testes de composição no CI que verificam os valores finais de configuração resolvidos.
- **Re-registrar workflow para cada mudança de profile:** Tratar cada adição de profile como um evento de re-registro de workflow. Planeje os profiles necessários antecipadamente (dev, staging, prod, test, test_full) e registre o workflow uma vez com todos os profiles definidos.

> **Nota do Arquiteto:** Na prática, a maior armadilha que vejo em equipes adotando essa feature não é técnica — é organizacional: a tendência de tratar profiles como uma solução para todos os problemas de configuração, incluindo segredos, versionamento de lógica e parametrização de negócio. O valor real de profiles é estreito e preciso: separar configurações de executor e plataforma do código científico. Quando mantido nesse escopo, o ganho de auditabilidade HIPAA e redução de drift entre ambientes é genuíno e mensurável. O que eu faria em qualquer implementação nova: definir no primeiro dia os profiles canônicos (`test`, `prod`, `staging`) com limites de recurso baseados em benchmarks reais dos seus processos mais pesados, e criar um teste de CI que executa o workflow com `-profile test` em cada PR — não como validação científica, mas como smoke test de configuração. Essa disciplina, aplicada consistentemente, elimina 80% dos incidentes de configuração que eu já vi em ambientes de bioinformática clínica.

## Avaliação pelos Pilares Well-Architected

- **security**: Profiles não carregam credenciais; engineOptions é capturado em audit logs. Combine com IAM conditions em omics:StartRun para restringir profiles de produção a roles específicas. KMS SSE-KMS em S3 de input/output permanece independente da feature de profiles.
- **reliability**: Runs com profile test permitem validação rápida de mudanças de workflow antes de promoção para prod. Reduza o MTTR de configuração incorreta eliminando edições manuais de arquivos de configuração entre ambientes.
- **performance**: Profiles de produção com withName/withLabel permitem alocar recursos precisos por tipo de processo (alinhamento vs. variant calling), evitando both over-provisioning e OOM kills que reiniciam tasks.
- **cost**: Profile test com datasets sintéticos reduz custo de runs de CI/CD em 40-60% vs. rodar com dados completos. Profiles de dev com limites menores evitam que explorações científicas consumam recursos de produção inadvertidamente.

## Veredicto: Adote, com Governança de Profiles desde o Dia Zero

O suporte a Nextflow profiles no AWS HealthOmics é uma mudança arquitetural genuinamente valiosa para equipes que operam pipelines bioinformáticos em ambientes regulados. A decisão de manter o artefato de workflow imutável enquanto permite variação de configuração em tempo de execução é a escolha correta para ambientes HIPAA — ela preserva a rastreabilidade do código científico enquanto oferece flexibilidade operacional real. A recomendação prática é clara: migre para profiles agora se você mantém múltiplas definições de workflow para o mesmo pipeline, ou se você usa workflows nf-core e estava adaptando-os manualmente para o HealthOmics. Defina os profiles canônicos (test, prod, staging) no momento do registro do workflow, não depois. Implemente IAM conditions para restringir profiles de produção a roles autorizadas. Monitore a composição de profiles em runs automatizados para detectar sobrescritas silenciosas. A feature é sólida; a governança em torno dela é o que determina se você colhe os benefícios ou acumula uma nova categoria de dívida técnica.

**Rating:** Adopt

## Referências

- [AWS HealthOmics Nextflow engine settings — official docs](https://docs.aws.amazon.com/omics/latest/dev/starting-a-run.html#start-run-api-engine-settings)
- [AWS What's New: AWS HealthOmics now supports Nextflow profiles](https://aws.amazon.com/about-aws/whats-new/2026/06/aws-healthomics-nextflow-profiles/)
- [AWS HealthOmics service page](https://aws.amazon.com/healthomics/)
- [Nextflow profiles documentation (Nextflow official)](https://www.nextflow.io/docs/latest/config.html#config-profiles)
- [nf-core pipeline profiles documentation](https://nf-co.re/docs/usage/configuration)
- [AWS Well-Architected Framework — Operational Excellence Pillar](https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/welcome.html)
- [AWS Step Functions — HealthOmics integration](https://docs.aws.amazon.com/step-functions/latest/dg/connect-omics.html)