Connecting HealthOmics workflows to a VPC

With Amazon Virtual Private Cloud (Amazon VPC), you can launch AWS resources in a private, virtual network that you've defined. You can give your HealthOmics workflows access to resources in your VPC by configuring your runs to use VPC networking mode. When VPC networking is enabled, your runs can access resources within your VPC and connect to external resources over the public internet if your VPC has internet access configured.

When to use VPC networking

Use VPC networking when your runs need to:

Networking modes

HealthOmics Workflows supports two networking modes. By default, workflow runs operate in RESTRICTED mode. You can enable VPC networking on a per-run basis when you start the workflow run.

You specify the networking mode when you start a workflow run using the networkingMode parameter in the StartRun API.

Getting started

This section guides you through setting up VPC networking for HealthOmics Workflows for the first time.

Prerequisites

Before configuring VPC networking for HealthOmics Workflows, ensure that you have the following:

Step 1: Create or configure your VPC

Create a VPC with private subnets, security groups, and NAT gateways (if internet access is needed). For detailed step-by-step instructions, see Internet access for VPC-connected workflows.

Step 2: Configure security groups

Create a security group that allows outbound traffic to the destinations your runs need to access. Configure security groups to allow only the minimum required outbound traffic following the principle of least privilege.

For example configurations and detailed guidance, see the security group section in Internet access for VPC-connected workflows.

Step 3: Verify route tables

Ensure your private subnets have routes to a NAT Gateway for internet access. For example route table configurations, see the route table section in Internet access for VPC-connected workflows.

Step 4: Create a configuration resource

Create a HealthOmics Configuration resource that defines your VPC networking settings:

aws omics create-configuration \
  --name my-vpc-config \
  --description "VPC configuration for genomics workflows" \
  --run-configurations '{
    "vpcConfig": {
      "securityGroupIds": ["sg-0123456789abcdef0"],
      "subnetIds": [
        "subnet-0a1b2c3d4e5f6g7h8",
        "subnet-1a2b3c4d5e6f7g8h9"
      ]
    }
  }' \
  --region us-west-2

The configuration will transition from CREATING to ACTIVE status once network resources are provisioned. This takes up to 15 minutes.

Step 5: Start a workflow run with VPC networking

Once your configuration is ACTIVE, start a workflow run with VPC networking enabled:

aws omics start-run \
  --workflow-id 1234567 \
  --role-arn arn:aws:iam::123456789012:role/OmicsWorkflowRole \
  --output-uri s3://my-bucket/outputs/ \
  --networking-mode VPC \
  --configuration-name my-vpc-config \
  --region us-west-2

Step 6: Verify connectivity

Monitor your workflow run to verify it can access the required external resources. Check the workflow logs in CloudWatch Logs for connection success or failure messages. For detailed guidance on testing connectivity, see Testing VPC connectivity.

VPC requirements

Your VPC must meet the following requirements:

Subnet requirements

Security group requirements

Security groups control inbound and outbound traffic for your runs.

Network interface requirements

HealthOmics provisions elastic network interfaces (ENIs) in your VPC to connect runs to your network. Ensure your AWS account has sufficient ENI capacity (default limit: 5,000 ENIs per Region).

ENIs created by HealthOmics are tagged with the following tags:

"TagSet": [
  {
    "Key": "Service",
    "Value": "HealthOmics"
  },
  {
    "Key": "eniType",
    "Value": "CUSTOMER"
  }
]

Configuration APIs

HealthOmics provides APIs to create, manage, and delete VPC configurations. You can reuse configurations across multiple workflow runs.

CreateConfiguration

Creates a new configuration resource with VPC networking settings. For a step-by-step example, see Step 4: Create a configuration resource.

Request syntax:

aws omics create-configuration \
  --name configuration-name \
  --description description \
  --run-configurations '{"vpcConfig":{"securityGroupIds":["security-group-id"],"subnetIds":["subnet-id"]}}' \
  --tags Key=key,Value=value \
  --region region

Parameters:

Response:

{
  "arn": "arn:aws:omics:region:account-id:configuration/configuration-name",
  "uuid": "configuration-uuid",
  "name": "configuration-name",
  "runConfigurations": {
    "vpcConfig": {
      "securityGroupIds": ["security-group-id"],
      "subnetIds": ["subnet-id"],
      "vpcId": "vpc-id"
    }
  },
  "status": "CREATING",
  "creationTime": "timestamp",
  "tags": {}
}

Configuration status values:

GetConfiguration

Retrieves details of a specific configuration.

Request syntax:

aws omics get-configuration \
  --name configuration-name \
  --region region

Response:

{
  "arn": "arn:aws:omics:region:account-id:configuration/configuration-name",
  "uuid": "configuration-uuid",
  "name": "configuration-name",
  "runConfigurations": {
    "vpcConfig": {
      "securityGroupIds": ["security-group-id"],
      "subnetIds": ["subnet-id"],
      "vpcId": "vpc-id"
    }
  },
  "status": "ACTIVE",
  "creationTime": "timestamp",
  "tags": {}
}

ListConfigurations

Lists all configurations in your account.

Request syntax:

aws omics list-configurations \
  --region region

Response:

{
  "items": [
    {
      "arn": "arn:aws:omics:region:account-id:configuration/configuration-name",
      "name": "configuration-name",
      "description": "description",
      "status": "ACTIVE",
      "creationTime": "timestamp"
    }
  ]
}

DeleteConfiguration

Deletes a configuration. You cannot delete a configuration that is currently in use by active workflow runs.

Request syntax:

aws omics delete-configuration \
  --name configuration-name \
  --region region

Running workflows with VPC networking

Starting a run with VPC networking

To use VPC networking in a workflow run, specify the networking-mode parameter and the configuration-name:

aws omics start-run \
  --workflow-id 1234567 \
  --role-arn arn:aws:iam::123456789012:role/OmicsWorkflowRole \
  --output-uri s3://my-bucket/outputs/ \
  --networking-mode VPC \
  --configuration-name my-vpc-config \
  --region us-west-2

Parameters:

Viewing run network configuration

Use GetRun to view the networking configuration for a run:

aws omics get-run \
  --id run-id \
  --region region

The response includes the networking mode, configuration details, and VPC configuration. The following example shows the VPC-related fields from the response:

{
  "arn": "arn:aws:omics:region:account-id:run/run-id",
  "id": "run-id",
  "status": "status",
  "workflowId": "workflow-id",
  "networkingMode": "VPC",
  "configuration": {
    "name": "configuration-name",
    "arn": "arn:aws:omics:region:account-id:configuration/configuration-name",
    "uuid": "configuration-uuid"
  },
  "vpcConfig": {
    "subnets": ["subnet-id-1", "subnet-id-2"],
    "securityGroupIds": ["security-group-id"],
    "vpcId": "vpc-id"
  }
}

Configuration immutability

Workflows use a snapshot of the configuration as it existed when the run started. You can safely modify or delete configurations during run execution without affecting active runs.

Call caching considerations

When using VPC networking with call caching, ensure your workflow engine is configured appropriately. For detailed guidance on call caching per engine, see Engine-specific caching features.

Best practices

Security

Performance

Cost optimization

Operational

VPC networking quotas

The following table lists the quotas for VPC networking configurations:

To request a quota increase, open the Service Quotas console, choose AWS services, search for AWS HealthOmics, select the quota you want to increase, and choose Request quota increase. Quota increase requests are typically processed within 1-2 business days.