Configure external ECR repository resources

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

AWS external ECR repository resource

External 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.

Configuration attributes:

1. Account ID: The non-Workbench managed AWS account in which the ECR repository lives.
2. Region: The AWS region in which the ECR repository lives.
3. Repository name: (Optional) The ECR repository name; if omitted grant access to all private repositories in the provided account and region.
4. Role tag key prefix: (Optional) Prefix for IAM role tags used to access the repository. See AWS IAM role tags and the Granting access section below.

Resource creation

External ECR repository resources may be created in AWS-backed workspaces via the Workbench CLI. After setting your workspace via wb workspace set, run:

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"

Granting access

AWS pod account ID

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

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

Example output:

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

The pod account ID, 535002863113, is shown in the Discovery role ARN field.

Grant mechanism

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 repo permissions, targeted at the external ECR repo.
4. In the external AWS account, an IAM policy is attached to the ECR repo, granting 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:

{
  "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"
      ]
    }
  ]
}

Substitutions:

• <pod-aws-account-id>: The pod account ID from the AWS pod account ID section above.
• <workspace-id>: The workspace UUID containing the external ECR repository resource. This can be retrieved from the output of wb workspace describe --format=json

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 AWS HealthOmics documentation for more details.

Usage

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 Workbench custom apps.

Workflows

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

CLI

You may 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 repo using the AWS CLI.