Manage Amazon ECR private repository access in Lightsail - Amazon Lightsail

Manage Amazon ECR private repository access in Lightsail

Amazon Elastic Container Registry (Amazon ECR) is an AWS managed container image registry service that supports private repositories with resource-based permissions using AWS Identity and Access Management (IAM). You can give your Amazon Lightsail container services access to your Amazon ECR private repositories. Then, you can deploy images from your private repository to your container services.

You can manage access for your Lightsail container services and your Amazon ECR private repositories by using the Lightsail console or the AWS Command Line Interface (AWS CLI). However, we recommend that you use the Lightsail console because it simplifies the process.

For more information about container services, see Container services. For more information about Amazon ECR, see the Amazon ECR User Guide.

Contents

Required permissions

The user who will manage access for Lightsail container services to Amazon ECR private repositories must have one of the following permissions policies in IAM. For more information, see Adding and removing IAM identity permissions in the AWS Identity and Access Management User Guide.

Grant access to any Amazon ECR private repository

The following permissions policy grants a user permission to configure access to any Amazon ECR private repository.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "ManageEcrPrivateRepositoriesAccess", "Effect": "Allow", "Action": [ "ecr:SetRepositoryPolicy", "ecr:DescribeRepositories", "ecr:DeleteRepositoryPolicy", "ecr:GetRepositoryPolicy" ], "Resource": "arn:aws:ecr:*:AwsAccountId:repository/*" } ] }

In the policy, replace AwsAccountId with your AWS account ID number.

Grant access to a specific Amazon ECR private repository

The following permissions policy grants a user permission to configure access to a specific Amazon ECR private repository, in a specific AWS Region.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "ManageEcrPrivateRepositoriesAccess", "Effect": "Allow", "Action": [ "ecr:SetRepositoryPolicy", "ecr:DescribeRepositories", "ecr:DeleteRepositoryPolicy", "ecr:GetRepositoryPolicy" ], "Resource": "arn:aws:ecr:AwsRegion:AwsAccountId:repository/RepositoryName" } ] }

In the policy, replace the following example text with your own:

  • AwsRegion — The AWS Region code (for example, us-east-1) of the private repository. Your Lightsail container service must be in the same AWS Region as the private repositories that you want to access.

  • AwsAccountId — Your AWS account ID number.

  • RepositoryName — The name of the private repository for which you want to manage access.

Following is an example of the permissions policy populated with example values.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "ManageEcrPrivateRepositoriesAccess", "Effect": "Allow", "Action": [ "ecr:SetRepositoryPolicy", "ecr:DescribeRepositories", "ecr:DeleteRepositoryPolicy", "ecr:GetRepositoryPolicy" ], "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/my-private-repo" } ] }

Use the Lightsail console to manage access to private repositories

Complete the following procedure to use the Lightsail console to manage access for a Lightsail container service to an Amazon ECR private repository.

  1. Sign in to the Lightsail console.

  2. On the Lightsail home page, choose the Containers tab.

  3. Choose the name of the container service for which you want to configure access to an Amazon ECR private repository.

    Container service in the Lightsail console
  4. Choose the Images tab.

    Images tab in the container service management page of the Lightsail console
  5. Choose Add repository to grant access for your container service to an Amazon ECR private repository.

    Note

    You can choose Remove to remove access for your container service from a previously added Amazon ECR private repository.

    Amazon ECR private repositories section of the Images tab
  6. In the dropdown that appears, select the private repository that you would like to access, and then choose Add.

    Amazon ECR private repositories dropdown selection

    Lightsail takes a few moments to activate the Amazon ECR image puller IAM role for your container service, which includes a principal Amazon Resource Name (ARN). Lightsail then automatically adds the IAM role principal ARN to the permissions policy of the Amazon ECR private repository that you selected. This grants your container service access to the private repository and its images. Don't close the browser window until the modal that appears indicates that the process is completed and you can choose Continue.

    Modal confirming that permissions are being added to Amazon ECR private repository
  7. Choose Continue when the activation is completed.

    After the selected Amazon ECR private repository is added it is listed in the Amazon ECR private repositories section of the page. The page includes instructions for how to deploy an image from the private repository to your Lightsail container service. To use an image from your private repository, specify the URI format that is displayed on the page as the Image value when creating your container service deployment. In the URI that you specify, replace the example {image tag} with the tag of the image you want to deploy. For more information, see Create and manage container service deployments.

    Next steps after adding an Amazon ECR private repository

Use the AWS CLI to manage access to private repositories

Managing access for a Lightsail container service to an Amazon ECR private repository using the AWS Command Line Interface (AWS CLI) requires the following steps:

Important

We recommend that you use the Lightsail console to manage access for a Lightsail container service to an Amazon ECR private repository because it simplifies the process. For more information, see Use the Lightsail console to manage access to private repositories earlier in this guide.

  1. Activate or deactivate the Amazon ECR image puller IAM role — Use the AWS CLI update-container-service command for Lightsail to activate or deactivate the Amazon ECR image puller IAM role. A principal Amazon Resource Name (ARN) is created for the Amazon ECR image puller IAM role when you activate it. For more information, see the Activate or deactivate the Amazon ECR image puller IAM role section of this guide.

  2. Determine if your Amazon ECR private repository has a policy statement — After you activate the Amazon ECR image puller IAM role, you need to determine if the Amazon ECR private repository that you want to access with your container service has an existing policy statement. For more information, see Determine if your Amazon ECR private repository has a policy statement later in this guide.

    You add the IAM role principal ARN to your repository using one of the following methods, depending on whether your repository has an existing policy statement:

    1. Add a policy to a private repository that doesn't have a policy statement — Use the AWS CLI set-repository-policy command for Amazon ECR to add the Amazon ECR image puller role principal ARN for your container service to a private repository that has an existing policy. For more information, see Add a policy to a private repository that doesn't have a policy statement later in this guide.

    2. Add a policy to a private repository that has a policy statement — Use the AWS CLI set-repository-policy command for Amazon ECR to add the Amazon ECR image puller role for your container service to a private repository that doesn't have an existing policy. For more information, see Add a policy to a private repository that has a policy statement later in this guide.

Activate or deactivate the Amazon ECR image puller IAM role

Complete the following procedure to activate or deactivate the Amazon ECR image puller IAM role for your Lightsail container service. You can activate or deactivate the Amazon ECR image puller IAM role using the AWS CLI update-container-service command for Lightsail. For more information, see update-container-service in the AWS CLI Command Reference.

Note

You must install the AWS CLI and configure it for Lightsail before you can continue with this procedure. For more information, see Configure the AWS CLI to work with Lightsail.

  1. Open a Command Prompt or Terminal window.

  2. Enter the following command to update a container service and activate or deactivate the Amazon ECR image puller IAM role.

    aws lightsail update-container-service --service-name ContainerServiceName --private-registry-access ecrImagePullerRole={isActive=RoleActivationState} --region AwsRegionCode

    In the command, replace the following example text with your own:

    • ContainerServiceName — The name of the container service for which to activate or deactivate the Amazon ECR image puller IAM role.

    • RoleActivationState — The activation state of the Amazon ECR image puller IAM role. Specify true to activate the role, or false to deactivate it.

    • AwsRegionCode — The AWS Region code of the container service (for example, us-east-1).

    Examples:

    • To activate the Amazon ECR image puller IAM role:

      aws lightsail update-container-service --service-name my-container-service --private-registry-access ecrImagePullerRole={isActive=true} --region us-east-1
    • To deactivate the Amazon ECR image puller IAM role:

      aws lightsail update-container-service --service-name my-container-service --private-registry-access ecrImagePullerRole={isActive=false} --region us-east-1
  3. If you:

    • Activated the Amazon ECR image puller role — Wait at least 30 seconds after getting the previous response. Then, continue to the next step to get the principal ARN of the Amazon ECR image puller IAM role for your container service.

    • Deactivated the Amazon ECR image puller role — If you previously added the Amazon ECR image puller IAM role principal ARN to the permissions policy of your Amazon ECR private repository, you should remove that permissions policy from your repository. For more information, see Deleting a private repository policy statement in the Amazon ECR User Guide.

  4. Enter the following command to get the principal ARN of the Amazon ECR image puller IAM role for your container service.

    aws lightsail get-container-services --service-name ContainerServiceName --region AwsRegionCode

    In the command, replace the following example text with your own:

    • ContainerServiceName — The name of your container service for which to get the Amazon ECR image puller IAM role principal ARN.

    • AwsRegionCode — The AWS Region code of the container service (for example, us-east-1).

    Example:

    aws lightsail get-container-services --service-name my-container-service --region us-east-1

    Look for the ECR image puller IAM role principal ARN in the response. If a role is listed, copy it or write it down. You will need it for the next section of this guide. Next, you need to determine if there is an existing policy statement on the Amazon ECR private repository that you want to access with your container service. Continue to the Determine if your Amazon ECR private repository has a policy statement section of this guide.

Determine if your Amazon ECR private repository has a policy statement

Use the following procedure to determine if your Amazon ECR private repository has a policy statement. You can use the AWS CLI get-repository-policy command for Amazon ECR. For more information, see update-container-service in the AWS CLI Command Reference.

Note

You must install the AWS CLI and configure it for Amazon ECR before you can continue with this procedure. For more information, see Setting up with Amazon ECR in the Amazon ECR User Guide.

  1. Open a Command Prompt or Terminal window.

  2. Enter the following command to get the policy statement for a specific private repository.

    aws ecr get-repository-policy --repository-name RepositoryName --region AwsRegionCode

    In the command, replace the following example text with your own:

    • RepositoryName — The name of the private repository for which you want to configure access for a Lightsail container service.

    • AwsRegionCode — The AWS Region code of the private repository (for example, us-east-1).

    Example:

    aws ecr get-repository-policy --repository-name my-private-repo --region us-east-1

    You should see one of the following responses:

Add a policy to a private repository that doesn't have a policy statement

Complete the following procedure to add a policy to an Amazon ECR private repository that doesn't have a policy statement. The policy that you add must include the Amazon ECR image puller IAM role principal ARN of your Lightsail container service. This grants access for your container service to deploy images from the private repository.

Important

Lightsail automatically adds the Amazon ECR image puller role to your Amazon ECR private repositories when you use the Lightsail console to configure access. In that case, you don't have to manually add the Amazon ECR image puller role to your private repositories using the procedure in this section. For more information, see Use the Lightsail console to manage access to private repositories earlier in this guide.

You can add a policy to a private repository using the AWS CLI. You do this by creating a JSON file that contains the policy, and then referencing that file with the set-repository-policy command for Amazon ECR. For more information, see set-repository-policy in the AWS CLI Command Reference.

Note

You must install the AWS CLI and configure it for Amazon ECR before continuing with this procedure. For more information, see Setting up with Amazon ECR in the Amazon ECR User Guide.

  1. Open a text editor, and paste the following policy statement into a new text file.

    { "Version": "2008-10-17", "Statement": [ { "Sid": "AllowLightsailPull-ecr-private-repo-demo", "Effect": "Allow", "Principal": { "AWS": "IamRolePrincipalArn" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ] } ] }

    In the text, replace IamRolePrincipalArn with the Amazon ECR image puller IAM role principal ARN of your container service that you got earlier in this guide.

  2. Save the file as ecr-policy.json to an accessible location on your computer (for example, C:\Temp\ecr-policy.json on Windows or /tmp/ecr-policy.json on macOS or Linux).

  3. Write down the file path location of the ecr-policy.json file created. You will specify it in a command later in this procedure.

  4. Open a Command Prompt or Terminal window.

  5. Enter the following command to set the policy statement for the private repository that you want to access with your container service.

    aws ecr set-repository-policy --repository-name RepositoryName --policy-text file://path/to/ecr-policy.json --region AwsRegionCode

    In the command, replace the following example text with your own:

    • RepositoryName — The name of the private repository for which you want to add the policy.

    • path/to/ — The path to the ecr-policy.json file on your computer that you created earlier in this guide.

    • AwsRegionCode — The AWS Region code of the private repository (for example, us-east-1).

    Examples:

    • On Windows:

      aws ecr set-repository-policy --repository-name my-private-repo --policy-text file://C:\Temp\ecr-policy.json --region us-east-1
    • On macOS or Linux:

      aws ecr set-repository-policy --repository-name my-private-repo --policy-text file:///tmp/ecr-policy.json --region us-east-1

    Your container service is now able to access your private repository and its images. To use an image from your repository, specify the following URI as the Image value for your container service deployment. In the URI, replace the example tag with the tag of the image you want to deploy. For more information, see Create and manage container service deployments.

    AwsAccountId.dkr.ecr.AwsRegionCode.amazonaws.com/RepositoryName:ImageTag

    In the URI, replace the following example text with your own:

    • AwsAccountId — Your AWS account ID number.

    • AwsRegionCode — The AWS Region code of the private repository (for example, us-east-1).

    • RepositoryName — The name of the private repository from which to deploy a container image.

    • ImageTag — The tag of the container image from the private repository to deploy on your container service.

    Example:

    111122223333.dkr.ecr.us-east-1.amazonaws.com/my-private-repo:myappimage

Add a policy to a private repository that has a policy statement

Complete the following procedure to add a policy to an Amazon ECR private repository that has a policy statement. The policy that you add must include the existing policy and a new policy that contains the Amazon ECR image puller IAM role principal ARN of your Lightsail container service. This maintains the existing permissions on your private repository while also granting access for your container service to deploy images from the private repository.

Important

Lightsail automatically adds the Amazon ECR image puller role to your Amazon ECR private repositories when you use the Lightsail console to configure access. In that case, you don't have to manually add the Amazon ECR image puller role to your private repositories using the procedure in this section. For more information, see Use the Lightsail console to manage access to private repositories earlier in this guide.

You can add a policy to a private repository using the AWS CLI. You do this by creating a JSON file that contains the existing policy and the new policy. Then, reference that file with the set-repository-policy command for Amazon ECR. For more information, see set-repository-policy in the AWS CLI Command Reference.

Note

You must install the AWS CLI and configure it for Amazon ECR before you can continue with this procedure. For more information, see Setting up with Amazon ECR in the Amazon ECR User Guide.

  1. Open a Command Prompt or Terminal window.

  2. Enter the following command to get the policy statement for a specific private repository.

    aws ecr get-repository-policy --repository-name RepositoryName --region AwsRegionCode

    In the command, replace the following example text with your own:

    • RepositoryName — The name of the private repository for which you want to configure access for a Lightsail container service.

    • AwsRegionCode — The AWS Region code of the private repository (for example, us-east-1).

    Example:

    aws ecr get-repository-policy --repository-name my-private-repo --region us-east-1
  3. In the response, copy the existing policy and continue to the next step.

    You should copy only the content of the policyText that appears between the double quotes, as highlighted in the following example.

    Response to the get-repository-policy command for a private repository that doesn't have a policy statement
  4. Open a text editor, and paste the existing policy from your private repository that you copied in the previous step.

    The result should look like the following example.

    Example policy statement JSON file
  5. In the text that you pasted, replace \n with line breaks and delete the remaining \.

    The result should look like the following example.

    Example edited policy statement JSON file
  6. Paste the following policy statement at the end of the text file.

    , { "Version": "2008-10-17", "Statement": [ { "Sid": "AllowLightsailPull-ecr-private-repo-demo", "Effect": "Allow", "Principal": { "AWS": "IamRolePrincipalArn" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ] } ] }
  7. In the text, replace IamRolePrincipalArn with the Amazon ECR image puller IAM role principal ARN of your container service that you got earlier in this guide.

    The result should look like the following example.

    Example complete policy statement JSON file
  8. Save the file as ecr-policy.json to an accessible location on your computer (for example, C:\Temp\ecr-policy.json on Windows or /tmp/ecr-policy.json on macOS or Linux).

  9. Write down the file path location of the ecr-policy.json file. You will specify it in a command later in this procedure.

  10. Open a Command Prompt or Terminal window.

  11. Enter the following command to set the policy statement for the private repository that you want to access with your container service.

    aws ecr set-repository-policy --repository-name RepositoryName --policy-text file://path/to/ecr-policy.json --region AwsRegionCode

    In the command, replace the following example text with your own:

    • RepositoryName — The name of the private repository for which you want to add the policy.

    • path/to/ — The path to the ecr-policy.json file on your computer that you created earlier in this guide.

    • AwsRegionCode — The AWS Region code of the private repository (for example, us-east-1).

    Examples:

    • On Windows:

      aws ecr set-repository-policy --repository-name my-private-repo --policy-text file://C:\Temp\ecr-policy.json --region us-east-1
    • On macOS or Linux:

      aws ecr set-repository-policy --repository-name my-private-repo --policy-text file:///tmp/ecr-policy.json --region us-east-1

    You should see a response similar to the following example.

    Response to the set-repository-policy command

    If you run the get-repository-policy command again, you should see the new additional policy statement on your private repository. Your container service is now able to access your private repository and its images. To use an image from your repository, specify the following URI as the Image value for your container service deployment. In the URI, replace the example tag with the tag of the image you want to deploy. For more information, see Create and manage container service deployments.

    AwsAccountId.dkr.ecr.AwsRegionCode.amazonaws.com/RepositoryName:ImageTag

    In the URI, replace the following example text with your own:

    • AwsAccountId — Your AWS account ID number.

    • AwsRegionCode — The AWS Region code of the private repository (for example, us-east-1).

    • RepositoryName — The name of the private repository from which to deploy a container image.

    • ImageTag — The tag of the container image from the private repository to deploy on your container service.

    Example:

    111122223333.dkr.ecr.us-east-1.amazonaws.com/my-private-repo:myappimage