Before you create a private workflow, you create a container image for your workflow. You upload the image to a private image repository in Amazon Elastic Container Registry (Amazon ECR). When you run the workflow, the HealthOmics service accesses the containers that you provide.
Container image Amazon ECR repository must reside in the same AWS Region as the account calling the service. A different AWS account can own the container image, as long as the source image repository provides appropriate permissions.
We recommend that you define your Amazon ECR container image URIs as parameters in your workflow so that access can be verified before the run begins. It also makes it easier to run a workflow in a new Region by changing the Region parameter.
Note
HealthOmics doesn't support ARM containers and doesn't support access to public repositories.
For information about configuring IAM permissions for HealthOmics to access Amazon ECR, see Resource permissions.
Topics
General considerations for Amazon ECR container images
-
Architecture
HealthOmics supports x86_64 containers. If your local machine is ARM-based, such as Apple Mac), use a command such as the following to build an x86_64 container image:
docker build --platform amd64 -t my_tool:latest . -
Entrypoint and shell
HealthOmics workflow engines inject bash scripts as a command override to the container images used by workflow tasks. Thus, container images should be built without a specified ENTRYPOINT such that a bash shell is the default.
-
Mounted paths
A shared filesystem is mounted to container tasks at /tmp. Any data or tooling built into the container image at this location will be overridden.
The workflow definition is available to tasks via a read-only mount at /mnt/workflow.
-
Image size
See HealthOmics workflow fixed size quotas for the maximum container image sizes.
Environment variables for HealthOmics workflows
HealthOmics provides environment variables that have information about the workflow running in the container. You can use the values of these variables in the logic of your workflow tasks.
All HealthOmics workflow variables start with the AWS_WORKFLOW_ prefix. This prefix is a protected
environment variable prefix. Don't use this prefix for your own variables in workflow containers.
HealthOmics provides the following workflow environment variables:
- AWS_REGION
-
This variable is the region where the container is running.
- AWS_WORKFLOW_RUN
-
This variable is the name of the current run.
- AWS_WORKFLOW_RUN_ID
-
This variable is the run identifier of the current run.
- AWS_WORKFLOW_RUN_UUID
-
This variable is the run UUID of the current run.
- AWS_WORKFLOW_TASK
-
This variable is the name of the current task.
- AWS_WORKFLOW_TASK_ID
-
This variable is the task identifier of the current task.
- AWS_WORKFLOW_TASK_UUID
-
This variable is the task UUID of the current task.
The following example shows typical values for each environment variable:
AWS Region: us-east-1 Workflow Run: arn:aws:omics:us-east-1:123456789012:run/6470304 Workflow Run ID: 6470304 Workflow Run UUID: f4d9ed47-192e-760e-f3a8-13afedbd4937 Workflow Task: arn:aws:omics:us-east-1:123456789012:task/4192063 Workflow Task ID: 4192063 Workflow Task UUID: f0c9ed49-652c-4a38-7646-60ad835e0a2e
Using Java in Amazon ECR container images
If a workflow task uses a Java application such as GATK, consider the following memory requirements for the container:
-
Java applications use stack memory and heap memory. By default, the maximum heap memory is a percentage of the total available memory in the container. This default depends on the specific JVM distribution and JVM version, so consult the relevant documentation for your JVM or explicitly set the heap memory maximum using Java command line options (such as `-Xmx`).
-
Don't set the maximum heap memory to be 100% of the container's memory allocation, because the JVM stack also requires memory. Memory is also required for the JVM garbage collector and any other operating system processes running in the container.
-
Some Java applications, such as GATK, can use native method invocations or other optimizations such as memory mapping files. These techniques require memory allocations that are performed “off heap”, which aren't controlled by the JVM maximum heap parameter.
If you know (or suspect) that your Java application allocates off-heap memory, make sure your task memory allocation includes the off-heap memory requirements.
If these off-heap allocations cause the container to run out of memory, you typically won't see a Java OutOfMemory error, because the JVM doesn't control this memory.
Add task inputs to an ECR container image
Add all executables, libraries, and scripts needed to run a workflow task into the Amazon ECR image that's used to run the task.
It's best practice to avoid using scripts, binaries, and libraries that are
external to a tasks container image. This is especially important when using
nf-core workflows that use a bin directory as part of
the workflow package. While this directory will be available to the workflow task,
it's mounted as a read-only directory. Required resources in this directory should
be copied into the task image and made available at runtime or when building the
container image used for the task.
See HealthOmics workflow fixed size quotas for the maximum size of container image that HealthOmics supports.
