> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Private ECR for Workspace Images

# Using Private ECR Repositories for Workspace Images

<Warning> **Note**: When using a private image in combination with `gp validate`, you'll need to [authenticate against the private registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html) in your workspace. See [below](#use-oidc-with-a-private-ecr-repository-for-gp-validate) for an example of how to setup and authenticate using OIDC.</Warning>

<Info> This is because `gp validate` emulates a workspace start using the Docker daemon running in your workspace. To prevent unintended security repercussions, the credentials used during workspace start are not automatically made available in the workspace.</Info>

## Authenticating Enterprise with a Private ECR Repository

1. Navigate to the AWS account where the target ECR repository is located.
2. Modify the target ECR repositories resource policy (repositories > permissions) with the following entry:

   ```json theme={null}
   {
   	"Version": "2012-10-17",
   	"Statement": [
   		{
   			"Sid": "Gitpod Access",
   			"Action": [
   				"ecr:BatchCheckLayerAvailability",
   				"ecr:BatchGetImage",
   				"ecr:GetDownloadUrlForLayer"
   			],
   			"Effect": "Allow",
   			"Principal": {
   				"AWS": [
   					"arn:aws:iam::<your-gitpod-enterprise-aws-account-id>:root"
   				]
   			}
   		}
   	]
   }
   ```

## How to use an Image from a Private ECR Repository in a `.gitpod.yml` File

1. Ensure you've followed the authentication steps from the section above.
2. In your [`.gitpod.yml` file](/classic/user/references/gitpod-yml#gitpodyml), directly reference the private ECR image:

   ```yml .gitpod.yml theme={null}
   image: <aws-ecr-url-prefix>.amazonaws.com/<your-image-name:tag>
   ```

## How to use an Image from a Private ECR Repository in Combination with Custom Dockerfiles

1. Ensure you've followed the authentication steps from the section above.

2. In your project repository, create a Dockerfile that references your private ECR image:

   ```Dockerfile theme={null}
   FROM <aws-ecr-url-prefix>.amazonaws.com/<your-image-name:tag>

   # Add your customizations here
   ```

3. In your `.gitpod.yml` file, reference the Dockerfile:

   ```yml .gitpod.yml theme={null}
   image:
       file: Dockerfile
   ```

Ensure that your image and Dockerfile adhere to the same requirements described [here](/classic/user/configure/workspaces/workspace-image#custom-base-image).

## Use OIDC with a Private ECR Repository for `gp validate`

### Setup an Identity Provider

Ensure an **Identity Provider** (IDP) is [setup in IAM in the account hosting the Private ECR Repository for Gitpod Enterprise](/classic/user/integrations/aws).

> **Note**: IDP has [connectivity requirements](/classic/admin/reference/networking-data-flows#connectivity-requirements). Gitpod Enterprise can be configured to [expose Gitpod services publicly](/classic/admin/deploy-gitpod/cf-templates#expose-gitpod-services-publicly).

### Setup IAM in the account hosting the Private ECR Repo

1. The **Role** you create must have specific **Permissions** to allow developers to pull from the Private ECR Repo. The **Trust Relationship** is flexible.

   * The **Permissions** should look similar to:

   ```json theme={null}
   {
   	"Version": "2012-10-17",
   	"Statement": [
   		{
   			"Effect": "Allow",
   			"Action": [
   				"ecr:GetDownloadUrlForLayer",
   				"ecr:BatchGetImage",
   				"ecr:DescribeImages",
   				"ecr:BatchCheckLayerAvailability"
   			],
   			"Resource": "arn:aws:ecr:<*-or-your-ecr-repo-aws-region>:<your-aws-account-id-hosting-the-ecr-repo>:repository/<the-ecr-repo-name>"
   		},
   		{
   			"Effect": "Allow",
   			"Action": ["ecr:GetAuthorizationToken"],
   			"Resource": "*"
   		}
   	]
   }
   ```

   * The **Trust relationships** should look similar to the below, except the Conditions may vary depending on your needs:

   ```json theme={null}
   {
   	"Version": "2012-10-17",
   	"Statement": [
   		{
   			"Effect": "Allow",
   			"Principal": {
   				"Federated": "arn:aws:iam::<your-gitpod-enterprise-aws-account-id>:oidc-provider/services.<your-gitpod-enterprise-cell-name>.gitpod.cloud/idp"
   			},
   			"Action": "sts:AssumeRoleWithWebIdentity",
   			"Condition": {
   				"StringEquals": {
   					"services.<your-gitpod-enterprise-cell-name>.gitpod.cloud/idp:aud": "sts.amazonaws.com"
   				},
   				"StringLikeIfExists": {
   					"services.<your-gitpod-enterprise-cell-name>.gitpod.cloud/idp:sub": [
   						"https://<your-vcs-host>/<your-git-org>/<your-git-repo>/tree/*",
   						"referrer:jetbrains-gateway:*/https://<your-vcs-host>/<your-git-org>/<your-git-repo>/tree/*"
   					]
   				}
   			}
   		}
   	]
   }
   ```

   * The above condition restricts role usage to a single repo and all branches.
     * Refer to [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) if you require a more complicated set of Conditions.

2. Persist the ARN of the Role you've configured somewhere where developers can access it from a Gitpod Workspace.
   * For example, you could persist it as a [Repository Environment Variable](/classic/user/configure/repositories/environment-variables).

3. At this point, the new role is ready to be assumed by developers.

### Use OIDC to log into the Private ECR Repository

1. Ensure you've followed the steps above to setup an IAM Identity Provider and Role.

2. Ensure the AWS CLI is installed for your Gitpod Workspace.

3. Assume the role

   ```sh theme={null}
   # get temporary credentials using OIDC
   gp idp login aws --role-arn "$ROLE_ARN"

   # log into docker using the temporary credentials
   aws ecr get-login-password --region "AWS_REGION" | docker login --username AWS --password-stdin "$ECR_REGISTRY" 1>/dev/null 2>&1

   # for test purposes, you may verify the credentials like so
   aws sts get-caller-identity
   ```

4. At this point, you should be able to `gp validate`