Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions aws-healthomics/POWER.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Whenever you are asked to perform a task related to any of the following scenari
- Using a VPC and subnets owned by a different AWS account (security groups may be owned by either the requester or the VPC owner) — RAM-shared VPCs (`vpcOwnerAccountId`), centralized egress, or VPC peering -> use `./steering/cross-account-vpc-configuration-setup.md`
- Understanding regional feature availability, GPU instance limitations, or troubleshooting region-specific errors -> use `./steering/regional-capabilities.md`
- Scoping down a workflow run's IAM permissions with an inline session policy (the StartRun / StartRunBatch `sessionPolicy` parameter) -> use `./steering/session-policy.md`
- Choosing x86_64 or ARM64 compute for a run or task (`runtimePlatformPreference`, task-level `runtimePlatform`) -> use `./steering/runtime-platform.md`


# Onboarding
Expand Down
1 change: 1 addition & 0 deletions aws-healthomics/steering/batch-runs.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ The IAM service role passed in `roleArn` requires the same permissions as for in
- `outputUri` — S3 output location (check `.healthomics/config.toml`).
- `storageType` — Use `DYNAMIC` (recommended).
- `sessionPolicy` — Optional; an inline IAM policy (JSON) that scopes down the permissions of `roleArn` for every run in the batch (effective permissions = the intersection of the role's policies and this policy). Applies uniformly to all runs in the batch. See the [Session Policies SOP](./session-policy.md).
- `runtimePlatformPreference` — Optional; `X86_64` or `ARM64` for every run in the batch. A run's own `inlineSettings` / `s3UriSettings` entry overrides it. See the [Runtime Platform SOP](./runtime-platform.md).
- `parameters` — Common parameters shared across all runs (e.g., reference genome).
3. Prepare per-run configurations, each with a unique `runSettingId` and any parameter overrides.

Expand Down
6 changes: 6 additions & 0 deletions aws-healthomics/steering/running-a-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ Follow this SOP WHEN:

> **Tooling support**: `sessionPolicy` is part of the HealthOmics REST API but is not exposed by every AWS CLI/SDK/MCP client version. Confirm the client you use accepts it before relying on it (e.g., `aws omics start-run help` should list `--session-policy`); older clients reject it as an unknown parameter.

### Compute Architecture

`StartRun` accepts an optional `runtimePlatformPreference` — `X86_64` or `ARM64` — applied to tasks that do not set their own architecture; inferred from the container image if omitted. See the [Runtime Platform SOP](./runtime-platform.md).

> **Tooling support**: `runtimePlatformPreference` is part of the HealthOmics API but is not exposed by every AWS CLI/SDK/MCP client version. Confirm the client accepts it (e.g., `aws omics start-run help` lists `--runtime-platform-preference`). IF the HealthOmics MCP tool rejects it, use the AWS CLI for that call — DO NOT silently drop the setting.

### Engine Settings

`StartRun` accepts an `engineSettings` map that customizes how HealthOmics invokes the workflow engine. The map is engine-agnostic in concept; today only Nextflow keys are implemented, so pass it only for Nextflow workflows. Pass it only when the user requests the corresponding behavior.
Expand Down
96 changes: 96 additions & 0 deletions aws-healthomics/steering/runtime-platform.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# SOP: Choosing the Compute Architecture (`runtimePlatformPreference`)

## Purpose

This SOP defines how you, the agent, choose whether a HealthOmics run's workflow tasks run
on `X86_64` or `ARM64` compute, at the run level and per task.

## Trigger Conditions

Follow this SOP WHEN:
- The user asks to run tasks on ARM64 / AWS Graviton, or to force x86_64.
- The user asks about `runtimePlatformPreference`, the task-level `runtimePlatform` setting,
or the `runtimePlatform` / `supportedArchitectures` fields on a task.
- A run fails with failure reason `UNSUPPORTED_RUNTIME_PLATFORM_TYPE`, or
`UNSUPPORTED_GPU_INSTANCE_TYPE` mentioning ARM64.

## Key Concepts

- **`runtimePlatformPreference`** — Optional `StartRun` parameter (`X86_64` or `ARM64`)
applied to every workflow task that does not set its own architecture. For batch runs,
set it in `defaultRunSetting`; a run's own `inlineSettings` / `s3UriSettings` entry
overrides it. The value MUST be exactly `X86_64` or `ARM64` (uppercase); any other value
is rejected with `RuntimePlatformPreference has an invalid value`. In a batch, an invalid
per-run value fails only that run, when the batch submits it.
- **Task-level override** — Set the architecture for one task in the workflow definition:
- WDL: `runtime { runtimePlatform: "ARM64" }`
- Nextflow: `ext.runtimePlatform = 'ARM64'` (in the process definition or `withName:`
config)
- CWL: `runtimePlatform: ARM64` in the task's `ResourceRequirement`

Task-level values are case-insensitive (`arm64` is accepted). An unrecognized task-level
value is silently ignored and the architecture is inferred.
- **Precedence** — task-level setting > `runtimePlatformPreference` > inferred from the
container image.
- **Inference** (when nothing is set):
- an ARM64-only image runs on ARM64;
- an x86-only image, or one whose architecture cannot be detected, runs on x86_64;
- a multi-architecture image runs on x86_64 unless ARM64 is requested.

Tasks that request GPUs, an `acceleratorType`, or a GPU fallback profile are inferred as
x86_64; explicitly requesting `ARM64` for them fails the run.
- **Scope** — The preference applies to workflow tasks only.
- **Reruns** inherit `runtimePlatformPreference` from the source run unless the rerun sets
one.
- `GetRun` / `ListRuns` return `runtimePlatformPreference`. `GetRunTask` returns
`runtimePlatform` (the architecture the task was placed on, when reported) and
`supportedArchitectures` (the architectures in the task's container image manifest).

## Procedure

1. Check that every container image used by the affected tasks has an image for the chosen
architecture (for example, `docker manifest inspect <image>` or
`aws ecr batch-get-image`). An explicit architecture is honored even if the image does
not support it — an `ARM64` request on an x86-only image, or an `X86_64` request on an
ARM64-only image, places the task on an architecture its container cannot run on.
2. Prefer setting the architecture per task when only some tools have ARM64 images; use
`runtimePlatformPreference` when the whole workflow is ARM64-ready.
3. DO NOT request `ARM64` for GPU tasks — GPU instance types are not supported with ARM64.
4. Start the run:

```bash
aws omics start-run \
--workflow-id <workflow-id> \
--role-arn arn:aws:iam::<account>:role/<role> \
--output-uri s3://<output-bucket>/<output-prefix>/ \
--runtime-platform-preference ARM64 \
--parameters file:///path/to/parameters.json
```

5. Verify with `aws omics get-run-task --id <run-id> --task-id <task-id>` (the
`GetAHORunTask` MCP tool does not return this field): when reported, `runtimePlatform`
shows where each task ran.

IF you change task-level `runtimePlatform` settings in the workflow definition, create a new
workflow version — see the [Workflow Versioning SOP](./workflow-versioning.md).

## Tooling Support

`runtimePlatformPreference` is part of the HealthOmics API but is not exposed by every
client. Check `aws omics start-run help` lists `--runtime-platform-preference`; IF not, ask
the user to upgrade the CLI/SDK. IF the HealthOmics MCP server's run tools lack the
parameter, use the AWS CLI for that call. The `GetAHORun` and `GetAHORunTask` MCP tools do
not return `runtimePlatformPreference` or `runtimePlatform`; read them with
`aws omics get-run` / `aws omics get-run-task`.

## Troubleshooting

| Run failure reason / error | Fix |
| --- | --- |
| `UNSUPPORTED_GPU_INSTANCE_TYPE` (mentions ARM64) | Remove the ARM64 request for GPU tasks (task-level setting or run preference). |
| `UNSUPPORTED_RUNTIME_PLATFORM_TYPE` | ARM64 compute is not available in this Region (currently Israel (Tel Aviv)). Remove the ARM64 request, or, IF the task's image is ARM64-only, use an x86_64 or multi-architecture image. |
| `RuntimePlatformPreference has an invalid value` | Use exactly `X86_64` or `ARM64`. |

## Related Documentation
- [Running a Workflow SOP](./running-a-workflow.md)
- [Batch Runs SOP](./batch-runs.md)
3 changes: 2 additions & 1 deletion aws-healthomics/steering/workflow-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,8 @@ This SOP defines how you, the agent, create and deploy genomics workflows for AW
- Use the `ListECRRepositories`, `CheckContainerAvailability` tools to find existing containers
- Use the `CloneContainerToECR` tool to add containers to ECR
- IF suitable containers cannot be found you SHOULD create appropriate Dockerfiles, build the images and push them to ECR
- You MUST use x86_64 architecture containers `--platform linux/amd64`
- By default, build x86_64 containers (`--platform linux/amd64`).
- WHEN the user wants ARM64 / AWS Graviton, build images that include an ARM64 variant; prefer multi-architecture images (`docker buildx build --platform linux/amd64,linux/arm64 ...`) so tasks can also run on x86_64. See the [Runtime Platform SOP](./runtime-platform.md).

### parameters.json
- You MUST define an example `parameters.json` for the workflow.
Expand Down
Loading