Managing Amazon Lightsail container service access to Amazon ECR private repositories

Last updated: September 15, 2022

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 in Amazon Lightsail. For more information about Amazon ECR, see the Amazon ECR User Guide.

Contents

• Required permissions

• Use the Lightsail console to manage access to private repositories

• Use the AWS CLI to manage access to private repositories

  • Activate or deactivate the Amazon ECR image puller IAM role

  • Determine if your Amazon ECR private repository has a policy statement

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

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

• Additional information about container services

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.

   

4. Choose the Images tab.

   

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.

   

6. In the dropdown that appears, select the private repository that you would like to access, and then choose Add.

   

   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.

   

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 Creating and managing deployments for your Amazon Lightsail container services.

   

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 CLIupdate-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 CLIset-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 CLIset-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 CLIupdate-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 Configuring the AWS Command Line Interface to work with Amazon 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 CLIget-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:

   • RepositoryPolicyNotFoundException — Your private repository does not have a policy statement. If your repository doesn't have a policy statement, follow the steps in the Add a policy to a private repository that doesn't have a policy statement section later in this guide.

     

   • A repository policy was found - Your private repository has a policy statement, and it is displayed in the response of your request. If your repository has a policy statement, copy the existing policy and then follow the steps in the Add a policy to a private repository that has a policy statement section later in this guide.

     

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 Creating and managing deployments for your Amazon Lightsail container services.

   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.

   

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.

   

5. In the text that you pasted, replace \n with line breaks and delete the remaining \.

   The result should look like the following example.

   

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.

   

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.

    

    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 Creating and managing deployments for your Amazon Lightsail container services.

    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

Additional information about container services

Following are the general steps to manage your Lightsail container service after it is running:

1. Familiarize yourself with all of the elements of Lightsail container services. For more information, see Container services in Amazon Lightsail.

2. Create your container service in your Lightsail account. For more information, see Creating Amazon Lightsail container services.

3. If you plan to use container images from a public registry, find container images from a public registry, such as the Amazon ECR Public Gallery. For more information about Amazon ECR Public, see What Is Amazon Elastic Container Registry Public? in the Amazon ECR Public User Guide.

4. If you plan to push container images from your local machine to your service, install software on your local machine that you need to create your own container images and push them to your Lightsail container service. For more information, see the following guides:

   • Installing software to manage container images for your Amazon Lightsail container services

   • Creating container images for your Amazon Lightsail container services

   • Pushing and managing container images on your Amazon Lightsail container services

5. Create a deployment in your container service that configures and launches your containers. For more information, see Creating and managing deployments for your Amazon Lightsail container services.

6. View previous deployments for your container service. You can create a new deployment using a previous deployment version. For more information, see Viewing and managing deployment versions of your Amazon Lightsail container services.

7. View the logs of containers on your container service. For more information, see Viewing the container logs of your Amazon Lightsail container services.

8. Create an SSL/TLS certificate for the domains that you want to use with your containers. For more information, see Creating SSL/TLS certificates for your Amazon Lightsail container services.

9. Validate the SSL/TLS certificate by adding records to the DNS of your domains. For more information, see Validating SSL/TLS certificates for your Amazon Lightsail container services.

10. Enable custom domains by attaching a valid SSL/TLS certificate to your container service. For more information, see Enabling and managing custom domains for your Amazon Lightsail container services.

11. Monitor the utilization metrics of your container service. For more information, see Viewing container service metrics in Amazon Lightsail.

12. (Optional) Scale the capacity of your container service vertically, by increasing its power specification, and horizontally, by increasing its scale specification. For more information, see Changing the capacity of your Amazon Lightsail container services.

13. To avoid incurring monthly charges, delete your container service if you're not using it. For more information, see Deleting Amazon Lightsail container services.