Configure external ECR repository resources

Purpose: This document covers how to create external ECR repository resources and configure access for them in a Verily Workbench AWS workspace.

Introduction

External Amazon Elastic Container Registry (ECR) repository resources enable AWS workspaces to access ECR repositories located outside of Workbench’s control. They are essential for running workflows and launching private image cloud apps.

Key ECR repository attributes

Create an external ECR repository resource

You can use the Workbench CLI to create external ECR repository resources in AWS-backed workspaces. After setting your workspace via wb workspace set, run the wb resource create ecr-external-repository command:

wb resource create ecr-external-repository \
  --account=000000000000 \
  --description="test external ecr repo" \
  --region="us-east-1" \
  --id="test-external-ecr" \
  --repository-name="test-external-ecr"

Grant access

AWS pod account ID

Your Workbench AWS pod is backed by a single AWS account. To view the pod account ID, run wb pod describe:

wb pod describe --pod=aws --org=verily1

Example output:

ID: aws
Organization: verily1
Description: AWS Pod
Cloud platform: AWS
Discovery role ARN: arn:aws:iam::535002863113:role/v0SaasTerraDiscovery
...

You can find the pod account ID in the Discovery role ARN field. In the example above, the pod account ID is 535002863113.

Grant cross-account access

To allow Workbench to access your ECR repository, grant cross-account access by attaching resource-based policies to your ECR repository.

The following diagram illustrates Workbench’s access model for provisioning permissions to external resources for HealthOmics workflows:

Access model steps:

1. Workbench provisions a temporary workflow execution IAM role for each AWS HealthOmics workflow run.
2. The role includes a custom tag attribute containing a workspace or data collection UUID and its scope of access.
3. Identity-based policies define ECR repository permissions, targeted at the external ECR repo.
4. In the external AWS account, an IAM policy is attached to the ECR repository. This grants permissions to the Workbench data plane account, conditioned on the custom attribute tag.

IAM policy configuration

To grant Workbench access to an individual ECR repository, use the following IAM policy template. Replace <pod-aws-account-id> with the pod account ID from the AWS pod account ID section above. Replace <workspace-id> with the workspace UUID containing the external ECR repository resource. This can be retrieved from the output of wb workspace describe --format=json.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CrossAccountOmicsExec",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<pod-aws-account-id>:root"
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Condition": {
        "StringEquals": {
          "aws:PrincipalType": "AssumedRole",
          "aws:PrincipalTag/vwb-<workspace-id>": ["reader", "writer"]
        }
      }
    },
    {
      "Sid": "OmicsWorkflow",
      "Effect": "Allow",
      "Principal": {
        "Service": "omics.amazonaws.com"
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ]
    }
  ]
}

The CrossAccountOmicsExec statement allows repository read permissions for IAM roles in the pod account with the vwb-<workspace-id> role tag. The role tag condition is optional but scopes access to only users with access to the workspace or data collection containing the external ECR repository resource.

The OmicsWorkflow statement allows repository read permissions for the omics.amazonaws.com service role to use images in the ECR repository as workflow task runner images. See the AWS HealthOmics documentation for more details.

Use an external ECR repository resource

Once access is configured, the following features are available in the workspace containing the external ECR repository resource:

Cloud apps

Custom apps may point to Docker images hosted in private ECR repositories. The image URI may be directly configured in a custom app devcontainer. To learn more, see Use custom apps.

Workflows

Once the HealthOmics service role has read permissions to the ECR repository, workflows can use images in the repository as task runner images. For more information, see Run WDL workflows on AWS-backed workspaces.

CLI

You can open a temporary AWS console session via wb resource open-console, or mint a temporary AWS session credential via wb resource credentials to push/pull images from the ECR repository using the AWS CLI.