# ADR: Nextflow Profiles on HealthOmics — Separating Config from Logic

AWS HealthOmics now supports Nextflow profiles, enabling predefined execution settings to be activated at runtime without modifying workflow source code. This analysis examines the architectural decision behind that separation of concerns, its real trade-offs, and the operational consequences for teams running bioinformatics pipelines at scale.

- 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=en

- 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/)

---

When configuration and logic live in the same file, any promotion from dev to prod becomes a regression risk. Nextflow profiles support on AWS HealthOmics solves exactly that problem — and the decision of how to structure that separation has consequences that reach far beyond operational convenience.

## Context and Forces: The Configuration Problem in Bioinformatics Pipelines

Bioinformatics pipelines have a characteristic that distinguishes them from general-purpose workloads: the same code needs to run correctly in radically different contexts. A variant calling pipeline processing 30x WGS in production may need to run with 2 CPUs and 8 GB RAM in development for fast validation, and with 64 vCPUs and 256 GB in production to meet clinical SLAs. Before profile support, the most common approach was to maintain separate `nextflow.config` files per environment or use environment variables with conditional logic embedded in the workflow code itself — both approaches violate the separation of concerns principle and introduce drift between environments.

In the AWS HealthOmics context, this problem is amplified by three specific forces. First: the service is HIPAA-eligible, meaning any change to workflow files must pass through audit controls — modifying `nextflow.config` to switch environments implies a different workflow artifact, with a different hash, requiring re-validation. Second: nf-core workflows — which represent the vast majority of pipelines adopted in production in the sector — already ship with institutional and platform profiles (`test`, `test_full`, `docker`, `singularity`, `awsbatch`), but without native profile support in HealthOmics, these profiles were ignored or required manual adaptation. Third: bioinformatics teams rarely have a dedicated SRE; the complexity of maintaining multiple workflow definitions for the same pipeline is a real operational cost that compounds with each new pipeline added to the portfolio.

## The Architectural Decision: What Actually Changed

The central decision here is not about Nextflow profiles themselves — that is a tooling feature that has existed for years. The decision is about **where the separation of configuration and logic should occur in the HealthOmics execution chain**. Before this change, HealthOmics treated the workflow as a complete, immutable artifact: everything that needed to vary between executions had to be passed as input parameters (`--param value`) or be embedded in the code. This worked for business parameters (which reference file to use, which sample to process), but was inadequate for platform configurations (CPU/memory limits per process, retry strategies, executor settings).

With profile support, HealthOmics now accepts an `engineOptions` field in the start-run API that allows specifying one or more profiles by name: `-profile test,aws`. This means the workflow artifact registered in the HealthOmics Workflow Registry remains immutable — same ARN, same SHA-256 hash — while execution behavior varies by the profile selected at run time. From a HIPAA audit perspective, this is significant: you can demonstrate that the scientific code was not altered between executions, while platform configurations vary in a controlled and traceable way through run parameters.

The most important design implication is that profiles are resolved at runtime by the Nextflow engine within HealthOmics' managed environment. This means the `nextflow.config` file inside the workflow artifact must define the profiles upfront — you cannot inject a profile that does not exist in the artifact. The flexibility is real, but it is bounded by what was defined at workflow registration time.

## Options Considered for Configuration Separation in HealthOmics

### Option A: Multiple Workflow Definitions per Environment

**Pros**
- Complete isolation between environments; no risk of wrong config in prod
- Each artifact is self-contained and independently auditable

**Cons**
- Drift between definitions is inevitable; any fix must be applied to N artifacts
- High operational cost: re-registration, re-validation, and re-testing for each promotion
- Violates DRY principle; increases human error surface

**Verdict:** Rejected — unsustainable operational cost in portfolios with 10+ pipelines

### Option B: Input Parameters for Platform Configurations

**Pros**
- Works with current HealthOmics API without modifications
- Traceable via run parameters in CloudWatch and HealthOmics Run History

**Cons**
- Semantic mixing: scientific and platform parameters in the same namespace
- nf-core workflows were not designed to receive executor configurations via params
- Does not solve per-process resource limits — requires conditional logic in DSL

**Verdict:** Partially adequate for business parameters; inadequate for executor configurations

### Option C: Nextflow Profiles via engineOptions (Decision Adopted)

**Pros**
- Workflow artifact remains immutable; clean separation of concerns
- Native compatibility with nf-core and existing institutional profiles
- Support for multiple composed profiles (-profile test,aws) for maximum flexibility
- Traceability via engineOptions in the run record; auditable for HIPAA

**Cons**
- Profiles must be defined in the registered artifact; no dynamic injection
- Adding a new profile requires re-registering the workflow (new ARN or new version)
- Composition complexity: profile order matters and can cause silent overrides

**Verdict:** Adopted — best balance of artifact immutability, auditability, and operational flexibility

## Workflow Lifecycle with Nextflow Profiles on HealthOmics

Separation between immutable artifact (registration) and variable configuration (profile selected at run time). The same workflow ARN serves dev, staging, and prod via distinct profiles.

### 🔧 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)

### Flows

- 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: same ARN
- omics_run -> s3_input: reads data
- omics_run -> s3_output: writes results
- omics_run -> cloudwatch: logs + engineOptions

## Operational Consequences: What Changes Day-to-Day for a Bioinformatics Team

The most immediate consequence is the elimination of an entire class of human errors: the accidental modification of production parameters during development edits. In teams I have observed, this type of error — a `maxMemory = 256.GB` that overwrites the dev limit of `8.GB` because someone edited the wrong file — accounts for a significant fraction of run failure incidents in HealthOmics. With profiles, the production configuration file is never touched during development.

The second consequence is about **nf-core workflow portability**. Pipelines like `nf-core/sarek`, `nf-core/rnaseq`, and `nf-core/viralrecon` already include profiles such as `test` (minimal dataset for CI), `test_full` (complete dataset for validation), and platform profiles like `awsbatch`. With native support in HealthOmics, teams can now register these workflows without modification and select the `test` profile for CI/CD validation and the production profile for clinical runs — using the same registered artifact. This reduces the onboarding time for a new nf-core pipeline from days to hours.

The third consequence, less obvious, is about **cost**. Development profiles with smaller CPU and memory limits mean that validation runs consume fewer HealthOmics managed resources. Given that HealthOmics charges per run time and allocated resources, the ability to run fast validations with the `test` profile — which typically uses 1-2 GB synthetic datasets instead of the 100-300 GB of a full WGS — can represent a 40-60% reduction in CI/CD run costs, depending on execution frequency.

## Designing for HIPAA Auditability: Profiles as Control Evidence

In HIPAA environments, traceability of every workflow execution is a requirement, not a convenience. The previous model — where environment configurations were embedded in the artifact or passed ad hoc — created audit gaps: it was difficult to demonstrate that a specific run used the correct configurations without inspecting the full artifact.

With profiles, the `engineOptions` field is captured in the HealthOmics run record and propagated to CloudWatch logs. This means that for each run, you have: (1) the workflow ARN with its SHA-256 hash, which uniquely identifies the scientific code; (2) the input parameters, which identify the processed data; and (3) the `engineOptions` with the selected profiles, which identifies the platform configuration. These three elements together form complete control evidence for auditing.

To maximize this traceability in a clinical-grade environment, I recommend structuring the Step Functions state machine that orchestrates HealthOmics runs to include the selected profile as an explicit execution attribute, not just passing it in `engineOptions`. This enables CloudWatch Logs Insights queries like `fields @timestamp, workflowId, selectedProfile, runStatus | filter selectedProfile = 'prod' | stats count() by runStatus` for quick audits. Additionally, IAM policies with conditions on `omics:engineOptions` can be used to restrict which roles can start runs with the `prod` profile — an environment separation control that goes beyond what was previously possible.

> **Consequences and Failure Modes You Need to Know:** **1. Silent override in profile composition:** When you specify `-profile test,aws`, Nextflow applies profiles left to right, with the last one winning on conflict. If the `aws` profile sets `process.memory = '16 GB'` and the `test` profile sets `process.memory = '4 GB'`, the order `-profile aws,test` will result in 4 GB — the opposite of what is expected for a production run that accidentally included `test`. There is no explicit warning from the engine; the run simply executes with the overridden configuration.

**2. Non-existent profile causes silent failure or late error:** If you specify a profile that does not exist in the registered artifact's `nextflow.config`, behavior depends on the Nextflow version: older versions silently ignore the non-existent profile; newer versions emit a warning but continue execution. In both cases, you do not get the expected behavior without a clear error. Validate existing profiles as part of your CI pipeline before registration.

**3. Profiles do not override input parameters:** Settings defined via `params` in `nextflow.config` within a profile have lower precedence than parameters passed via `--param` on the command line or in the API's `parameters` field. This can cause confusion when a production profile defines `params.genome = 'GRCh38'` but the caller passes `--genome GRCh37` — the profile is ignored for that specific parameter.

**4. engineOptions field size limit:** The HealthOmics API has string field size limits. Long profile compositions with additional arguments may approach this limit. Monitor `engineOptions` size in automated runs.

## Integration with the AWS Ecosystem: Step Functions, IAM, and Observability

The profiles feature does not exist in a vacuum — it needs to be integrated into the orchestration and governance ecosystem surrounding HealthOmics. The most natural integration is with Step Functions, which typically serves as the orchestrator for bioinformatics workflows in production, managing run sequences, inter-pipeline dependencies, and error handling.

In practice, I recommend modeling the profile as an explicit input variable in the Step Functions state machine, not as a hardcoded value. The `StartHealthOmicsRun` state should receive `$.profile` as input and dynamically construct the `engineOptions`: `"engineOptions": { "nextflow": { "profile": "$.profile" } }`. This allows the same state machine to serve both dev and prod, with the profile determined by the event that triggers the execution — a CI event passes `test`, a clinical production event passes `prod,aws`.

From an IAM perspective, profile separation opens a control opportunity that did not previously exist. You can create an IAM policy that uses `StringLike` conditions on `omics:engineOptions` to restrict which roles can start runs with production profiles. For example, a CI/CD role can be limited to starting only runs with `-profile test` or `-profile test_full`, while the clinical execution role has permission for `-profile prod,aws`. This implements environment separation at the control plane, not just the data plane.

For observability, the most valuable signal is correlating the selected profile with run cost and duration metrics. A CloudWatch Logs Insights query that groups `runDuration` and `estimatedCost` by `selectedProfile` allows you to quickly identify whether development runs are inadvertently using production profiles — an early warning signal for both cost waste and potential configuration leakage.

## Anti-Patterns to Avoid with Nextflow Profiles on HealthOmics

- **Profile as versioning substitute:** Using profiles to manage algorithm versions (e.g., `profile_v1`, `profile_v2`) instead of workflow versions. Profiles are for platform configuration, not scientific logic. Different logic = different artifact.
- **Credentials or secrets in profiles:** Never place KMS key ARNs, database endpoints, or any sensitive data directly in profiles within `nextflow.config`. Use SSM Parameter Store or Secrets Manager and reference via environment variables in the process.
- **Single profile for all processes:** Defining a monolithic profile that applies the same CPU/memory limits to all workflow processes. Alignment processes (BWA-MEM2) have radically different resource profiles from variant calling processes (GATK HaplotypeCaller). Use `withName` or `withLabel` within profiles for per-process granularity.
- **Ignoring profile composition order:** Assuming the order of profiles in `-profile a,b,c` does not matter. Always document the expected order and include composition tests in CI that verify the final resolved configuration values.
- **Re-registering workflow for every profile change:** Treating each profile addition as a workflow re-registration event. Plan the required profiles upfront (dev, staging, prod, test, test_full) and register the workflow once with all profiles defined.

> **Architect's Note:** In practice, the biggest trap I see in teams adopting this feature is not technical — it is organizational: the tendency to treat profiles as a solution for all configuration problems, including secrets, logic versioning, and business parameterization. The real value of profiles is narrow and precise: separating executor and platform configurations from scientific code. When kept within that scope, the HIPAA auditability gain and reduction of environment drift is genuine and measurable. What I would do in any new implementation: define on day one the canonical profiles (`test`, `prod`, `staging`) with resource limits based on real benchmarks of your heaviest processes, and create a CI test that runs the workflow with `-profile test` on every PR — not as scientific validation, but as a configuration smoke test. That discipline, applied consistently, eliminates 80% of the configuration incidents I have seen in clinical bioinformatics environments.

## Well-Architected Pillars Assessment

- **security**: Profiles carry no credentials; engineOptions is captured in audit logs. Combine with IAM conditions on omics:StartRun to restrict production profiles to specific roles. KMS SSE-KMS on input/output S3 remains independent of the profiles feature.
- **reliability**: Runs with the test profile enable fast validation of workflow changes before promotion to prod. Reduce MTTR from incorrect configuration by eliminating manual config file edits between environments.
- **performance**: Production profiles with withName/withLabel allow precise resource allocation per process type (alignment vs. variant calling), avoiding both over-provisioning and OOM kills that restart tasks.
- **cost**: Test profile with synthetic datasets reduces CI/CD run costs by 40-60% vs. running with full data. Dev profiles with smaller limits prevent scientific explorations from inadvertently consuming production-grade resources.

## Verdict: Adopt, with Profile Governance from Day Zero

Nextflow profiles support on AWS HealthOmics is a genuinely valuable architectural change for teams operating bioinformatics pipelines in regulated environments. The decision to keep the workflow artifact immutable while allowing configuration variation at runtime is the correct choice for HIPAA environments — it preserves scientific code traceability while offering real operational flexibility. The practical recommendation is clear: migrate to profiles now if you maintain multiple workflow definitions for the same pipeline, or if you use nf-core workflows and were manually adapting them for HealthOmics. Define the canonical profiles (test, prod, staging) at workflow registration time, not after. Implement IAM conditions to restrict production profiles to authorized roles. Monitor profile composition in automated runs to detect silent overrides. The feature is solid; the governance around it is what determines whether you reap the benefits or accumulate a new category of technical debt.

**Rating:** Adopt

## References

- [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)