# Build and test Docker images for Lightsail container services
Container images

With Docker, you can build, run, test, and deploy distributed applications that are based on containers. Amazon Lightsail container services use Docker container images in deployments to launch containers.

In this guide, we show you how to create a container image on your local machine using a Dockerfile. After your image is created, you can then push it to your Lightsail container service to deploy it.

To complete the procedures in this guide you should possess a basic understanding of what Docker is and how it works. For more information about Docker, see [What is Docker?](https://aws.amazon.com/docker/) and the [Docker overview](https://docs.docker.com/get-started/overview/).

**Contents**
+ [Step 1: Complete the prerequisites](#create-container-image-prerequisite)
+ [Step 2: Create a Dockerfile and build a container image](#create-container-image-create-dockerfile)
+ [Step 3: Run your new container image](#create-container-image-run-container)
+ [(Optional) Step 4: Clean up the containers running on your local machine](#create-container-image-cleanup)
+ [Next steps after creating container images](#create-container-image-next-steps)

## Step 1: Complete the prerequisites


Before you get started, you must install the software required to create containers and then push them to your Lightsail container service. For example, you must install and use Docker to create and build your container images that you can then use with your Lightsail container service. For more information, see [Installing software to manage container images for your Amazon Lightsail container services](amazon-lightsail-install-software.md).

## Step 2: Create a Dockerfile and build a container image


Complete the following procedure to create a Dockerfile, and build a `mystaticwebsite` Docker container image from it. The container image will be for a simple static website hosted on an Apache web server on Ubuntu.

1. Create a `mystaticwebsite` folder on your local machine where you will store your Dockerfile.

1. Create a Dockerfile in the folder you just created.

   The Dockerfile does not use a file extension, such as `.TXT`. The full file name is `Dockerfile`.

1. Copy one of the following code blocks depending on how you want to configure your container image, and paste it into your Dockerfile:
   + **If you want to create a simple static website container image with a Hello World message**, then copy the following code block and paste it into your Dockerfile. This code sample uses the Ubuntu 18.04 image. The `RUN` instructions updates the package caches, and installs and configures Apache, and prints a Hello World message to the web server's document root. The `EXPOSE` instruction exposes port 80 on the container, and the `CMD` instruction starts the web server.

     ```
     FROM ubuntu:18.04
     
     # Install dependencies
     RUN apt-get update && \
      apt-get -y install apache2
     
     # Write hello world message
     RUN echo 'Hello World!' > /var/www/html/index.html
     
     # Open port 80
     EXPOSE 80
     
     # Start Apache service
     CMD ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]
     ```
   + **If you want to use your own set of HTML files for your static website container image**, create an `html` folder in the same folder where you store your Dockerfile. Then put your HTML files in that folder.

     After your HTML files are in the `html` folder, copy the following code block and paste into to your Dockerfile. This code sample uses the Ubuntu 18.04 image. The `RUN` instructions updates the package caches, and installs and configures Apache. The `COPY` instruction copies the contents of the html folder to the web server's document root. The `EXPOSE` instruction exposes port 80 on the container, and the `CMD` instruction starts the web server.

     ```
     FROM ubuntu:18.04
     
     # Install dependencies
     RUN apt-get update && \
      apt-get -y install apache2
     
     # Copy html directory files
     COPY html /var/www/html/
     
     # Open port 80
     EXPOSE 80
     
     CMD ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]
     ```

1. Open a command prompt or terminal window and change the directory to the folder in which you are storing your Dockerfile.

1. Enter the following command to build your container image using the Dockerfile in the folder. This command builds a new Docker container image named `mystaticwebsite`.

   ```
   docker build -t mystaticwebsite .
   ```

   You should see a message that confirms your image was successfully built.

1. Enter the following command to view the container images on your local machine.

   ```
   docker images --filter reference=mystaticwebsite
   ```

   You should see a result similar to the following example, showing the new container image created.  
![\[Result of docker images command\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/docker-images-command-result.png)

   Your newly built container image is ready to be tested by using it to run a new container on your local machine. Continue to the next [Step 3: Run your new container image](#create-container-image-run-container) section of this guide.

## Step 3: Run your new container image


Complete the following steps to run the new container image you created.

1. In a command prompt or terminal window, enter the following command to run the container image that you built in the previous [Step 2: Create a Dockerfile and build a container image](#create-container-image-create-dockerfile) section of this guide. The `-p 8080:80` option maps the exposed port 80 on the container to port 8080 on your local machine. The `-d` option specifies that the container should run in detached mode.

   ```
   docker container run -d -p 8080:80 --name mystaticwebsite mystaticwebsite:latest
   ```

1. Enter the following command to view your running containers.

   ```
   docker container ls -a
   ```

   You should see a result similar to the following example, showing the new running container.  
![\[Result of docker container command\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/docker-container-command-result.png)

1. To confirm that the container is up and running, open a new browser window and browse to `http://localhost:8080`. You should see a message similar to the following example. This confirms that your container is up and running on your local machine.  
![\[Static website running on a Docker container\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-mystaticsite-hello-world.png)

   Your newly built container image is ready to be pushed to your Lightsail account so that you can deploy it to your Lightsail container service. For more information, see [Pushing and managing container images on your Amazon Lightsail container services](amazon-lightsail-pushing-container-images.md).

## (Optional) Step 4: Clean up the containers running on your local machine


Now that you've created a container image that you can push to your Lightsail container service, it's time to clean up the containers that are running on your local machine as a result of following the procedures in this guide.

Complete the following steps to clean up the containers running on your local machine:

1. Run the following command to view the containers that are running on your local machine.

   ```
   docker container ls -a
   ```

   You should see a result similar to the following, which lists the names of the containers running on your local machine.  
![\[Result of docker container command\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/docker-container-command-result.png)

1. Run the following command to remove the running container that you created earlier in this guide. This forces the container to be stopped, and permanently deletes it.

   ```
   docker container rm <ContainerName> --force
   ```

   In the command, replace <ContainerName> with the name of the container you want to stop, and delete.

   Example:

   ```
   docker container rm mystaticwebsite --force
   ```

   The container that was created as a result of this guide should now be deleted.

## Next steps after creating container images


After you create your container images, push them to your Lightsail container service when you're ready to deploy them. For more information, see [Manage Lightsail container service images](amazon-lightsail-pushing-container-images.md).

**Topics**
+ [

## Step 1: Complete the prerequisites
](#create-container-image-prerequisite)
+ [

## Step 2: Create a Dockerfile and build a container image
](#create-container-image-create-dockerfile)
+ [

## Step 3: Run your new container image
](#create-container-image-run-container)
+ [

## (Optional) Step 4: Clean up the containers running on your local machine
](#create-container-image-cleanup)
+ [

## Next steps after creating container images
](#create-container-image-next-steps)
+ [Manage container images](amazon-lightsail-pushing-container-images.md)
+ [Install container services plugin](amazon-lightsail-install-software.md)
+ [ECR private repository access](amazon-lightsail-container-service-ecr-private-repo-access.md)

# Push, view, and delete container images for a Lightsail container service
Manage container images

When you create a deployment in your Amazon Lightsail container service, you must specify a source container image for each container entry. You can use images from a public registry, such as Amazon ECR Public Gallery, or you can use images that you create on your local machine. In this guide, we show you how to push container images from your local machine to your Lightsail container service. For more information about creating container images, see [Create container service images](amazon-lightsail-creating-container-images.md).

**Contents**
+ [Prerequisites](#push-container-images-prerequisites)
+ [Push container images from your local machine to your container service](#push-container-images)
+ [View container images stored on your container service](#view-pushed-container-images)
+ [Delete container images stored on your container service](#delete-stored-container-images)

## Prerequisites


Complete the following prerequisites before you get started with pushing your container images to your container service:
+ Create your container service in your Lightsail account. For more information, see [Creating Amazon Lightsail container services](amazon-lightsail-creating-container-services.md).
+ 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 [Installing software to manage container images for your Amazon Lightsail container services](amazon-lightsail-install-software.md).
+ Create container images on your local machine, that you can push to your Lightsail container service. For more information, see [Creating container images for your Amazon Lightsail container services](amazon-lightsail-creating-container-images.md).

## Push container images from your local machine to your container service


Complete the following procedure to push your container images to your container service.

1. Open a command prompt or terminal window.

1. In the command prompt or terminal window, enter the following command to view the Docker images that are currently on your local machine.

   ```
   docker images
   ```

1. In the result, locate the name (repository name) and tag of the container image that you want to push to your container service. Make a note of it because you will need it in the next step.  
![\[Docker container images on a local machine\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/amazon-lightsail-container-service-docker-images.png)

1. Enter the following command to push the container image on your local machine to your container service.

   ```
   aws lightsail push-container-image --region <Region> --service-name <ContainerServiceName> --label <ContainerImageLabel> --image <LocalContainerImageName>:<ImageTag>
   ```

   In the command, replace:
   + *<Region>* with the AWS Region in which your container service was created.
   + *<ContainerServiceName>* with the name of your container service.
   + *<ContainerImageLabel>* with the label that you want to give your container image when it's stored on your container service. Specify a descriptive label that you can use to track the different versions of your registered container images.

     The label will be part of the container image name generated by your container service. For example, if your container service name is `container-service-1`, the container image label is `mystaticsite`, and this is the first version of the container image you're pushing, then the image name generated by your container service will be `:container-service-1.mystaticsite.1`.
   + *<LocalContainerImageName>* with the name of the container image that you want to push to your container service. You obtained the container image name in the previous step of this procedure.
   + *<ImageTag>* with the tag of the container image that you want to push to your container service. You obtained the container image tag in the previous step of this procedure.

   Example:

   ```
   aws lightsail push-container-image --region us-west-2 --service-name myservice --label mystaticwebsite --image mystaticwebsite:v2
   ```

   You should see a result similar to the following example, which confirms that your container image was pushed to your container service.  
![\[Docker container image pushed to a Lightsail container service\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/amazon-lightsail-container-service-pushed-image.png)

   Refer to the following [View container images stored on your container service](#view-pushed-container-images) section of this guide to view your pushed container image in your container service on the Lightsail console.

## View container images stored on your container service


Complete the following procedure to view container images that were pushed, and are being stored, on your container service.

1. Sign in to the [Lightsail console](https://lightsail.aws.amazon.com/).

1. In the left navigation pane, choose **Containers**.

1. Choose the name of the container service for which you want to view the stored container images.

1. On the container service management page, choose the **Images** tab.
**Note**  
The **Images** tab is not displayed if you have not pushed images to your container service. To display the images tab for your container service you must first push container images to your service.

   The **Images** page lists the container images that were pushed to your container service, and are currently being stored on your service. Container images that are being used in a current deployment cannot be deleted and are listed with a grayed-out delete icon.  
![\[The stored images page of the Lightsail console\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/amazon-lightsail-container-services-stored-images-page.png)

   You can create deployments using container images stored on your service. For more information, see Creating and managing deployments for your Amazon Lightsail container services.

## Delete container images stored on your container service


Complete the following procedure to delete container images that were pushed, and are being stored, on your container service.

1. Sign in to the [Lightsail console](https://lightsail.aws.amazon.com/).

1. In the left navigation pane, choose **Containers**.

1. Choose the name of the container service for which you want to view the current deployment.

1. On the container service management page, choose the **Images** tab.
**Note**  
The **Images** tab is not displayed if you have not pushed images to your container service. To display the images tab for your container service you must first push container images to your service.

1. Find the container image you want to delete, and choose the delete (trash bin) icon.
**Note**  
Container images that are being used in a current deployment cannot be deleted and their delete icons are grayed-out.

1. In the confirmation prompt that appears, choose **Yes, delete** to confirm that you want to permanently delete the stored image.

   Your stored container image is immediately deleted from your container service.

# Install Docker, AWS CLI, and the Lightsail Control plugin for containers
Install container services plugin

You can use the Amazon Lightsail console to create your Lightsail container services, and create deployments using container images from an online public registry, such as Amazon ECR Public Gallery. To create your own container images, and push them to your container service, you must install the following additional software on the same computer on which you plan to create your container images:
+ **Docker** – Run, test, and create your own container images that you can then use with your Lightsail container service.
+ **AWS Command Line Interface (AWS CLI)** – Specify parameters of the container images you create, and then push them to your Lightsail container service. Version 2.1.1 and later will work with the Lightsail Control plugin.
+ **Lightsail Control (lightsailctl) plugin** – Enables the AWS CLI to access the container images that are on the local machine.

The following sections of this guide describe where to go to download these software packages, and how to install them. For more information about container services, see [Container services](amazon-lightsail-container-services.md).

**Contents**
+ [Install Docker](#install-software-docker)
+ [Install the AWS CLI](#install-software-aws-cli)
+ [Install the Lightsail Control plugin](#install-software-lightsailctl)
  + [Install the lightsailctl plugin on Windows](#install-lightsailctl-on-windows)
  + [Install the lightsailctl plugin on macOS](#install-lightsailctl-on-macos)
  + [Install the lightsailctl plugin on Linux](#install-lightsailctl-on-linux)

## Install Docker


Docker is a technology that allows you to build, run, test, and deploy distributed applications that are based on Linux containers. You must install and use Docker software if you want to create your own container images that you can then use with your Lightsail container service. For more information, see [Create container images for your Lightsail container services](amazon-lightsail-creating-container-images.md).

Docker is available for many different operating systems, including most modern Linux distributions, like Ubuntu, and even macOS and Windows. For more information about how to install Docker on your particular operating system, see the [Docker installation guide](https://docs.docker.com/engine/installation/#installation).

**Note**  
Always install the latest version of Docker. Older versions of Docker are not guaranteed to work with the AWS CLI and Lightsail Control (lightsailctl) plugin described later in this guide. 

## Install the AWS CLI


The AWS CLI is an open source tool that enables you to interact with AWS services, such as Lightsail, using commands in your command-line shell. You must install and use the AWS CLI to push your container images, created on your local machine, to your Lightsail container service.

The AWS CLI is available in the following versions:
+ **Version 2.x** – The current, generally available release of the AWS CLI. This is the most recent major version of the AWS CLI and supports all of the latest features, including the ability to push container images to your Lightsail container services. Version 2.1.1 and later will work with the Lightsail Control plugin.
+ **Version 1.x** – The previous version of the AWS CLI that is available for backwards compatibility. This version does not support the ability to push your container images to your Lightsail container services. Therefore, you must install the AWS CLI version 2 instead.

The AWS CLI version 2 is available for Linux, macOS, and Windows operating systems. For instructions on how to install the AWS CLI on those operating systems, see [Installing the AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the *AWS CLI User Guide*.

## Install the Lightsail Control plugin


The Lightsail Control (lightsailctl) plugin is a lightweight application that allows the AWS CLI to access the container images that you created on your local machine. It allows you to push container images to your Lightsail container service, so that you can deploy them to your service.

**System requirements**
+ A Windows, macOS, or Linux operating system with 64-bit support.
+ AWS CLI version 2 must be installed on your local machine in order to use the lightsailctl plugin. For more information, see the [Install the AWS CLI](#install-software-aws-cli) section earlier in this guide.

**Use the latest version of the lightsailctl plugin**

The lightsailctl plugin is updated occasionally with enhanced functionality. Each time you use the lightsailctl plugin, it performs a check to confirm you're using the latest version. If it finds that a new version is available, it prompts you to update to the latest version to take advantage of the latest features. When an updated version is available, you must repeat the installation process to get the latest version of the lightsailctl plugin.

The following lists all releases of the lightsailctl plugin and the features and enhancements included with each version.
+ **v1.0.0 (released November 12, 2020)** – Initial release adds functionality for the AWS CLI version 2 to push container images to a Lightsail container service.

### Install the lightsailctl plugin on Windows


Complete the following procedure to install the lightsailctl plugin on Windows.

1. Download the executable from the following URL, and save it to the `C:\Temp\lightsailctl\` directory.

   ```
   https://s3.us-west-2.amazonaws.com/lightsailctl/latest/windows-amd64/lightsailctl.exe
   ```

1. Choose the **Windows Start** button, and then search for `cmd`.

1. Right-click the **Command Prompt** application in the results, and choose **Run as administrator**.  
![\[Run Command Prompt as administrator\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/lightsailctl-cmd-run-as-administrator.png)
**Note**  
You may see a prompt that asks if you want to allow Command Prompt to make changes to your device. You must choose **Yes** to continue with the installation.

1. Enter the following command to set a path environment variable that points to the `C:\Temp\lightsailctl\` directory where you saved the lightsailctl plugin.

   ```
   setx PATH "%PATH%;C:\Temp\lightsailctl" /M
   ```

   You should see a result similar to the following example.  
![\[Command line response to setx command\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/lighstailctl-setx-command.png)

The `setx` command will truncate beyond 1024 characters. Use the following procedure to manually set the path environment variable if you already have multiple variables set in your PATH. 

1. On the **Start** menu, open **Control Panel**.

1. Choose **System and Security**, then **System**.

1. Choose **Advanced system settings**.

1. On the **Advanced** tab of the **System Properties** dialog box, choose **Environment Variables**.

1. In the **System Variables** box of the **Environment Variables** dialog box, select **Path**.

1. Choose the **Edit** button located under the **System Variables** box.  
![\[Windows system variables\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/lightsail-windows-system-variables.png)

1. Choose **New**, then enter the following path: `C:\Temp\lightsailctl\`  
![\[Windows environment variables\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/lightsail-windows-edit-env-variable.png)

1. Choose **OK** in three successive dialog boxes, and then close the **System** dialog box.

You are now ready to use the AWS Command Line Interface (AWS CLI) to push container images to your Lightsail container service. For more information, see [Push and manage container images](amazon-lightsail-pushing-container-images.md).

### Install the lightsailctl plugin on macOS


Complete one of the following procedures to download and install the lightsailctl plugin on macOS.

**Homebrew download and install**

1. Open a terminal window.

1. Enter the following command to download and install the lightsailctl plugin.

   ```
   brew install aws/tap/lightsailctl
   ```
**Note**  
For more information about Homebrew, see the [Homebrew](https://brew.sh/) website.

**Manual download and install**

1. Open a terminal window.

1. Enter the following command to download the lightsailctl plugin and copy it to the bin folder.

   ```
   curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/darwin-amd64/lightsailctl" -o "/usr/local/bin/lightsailctl"
   ```

1. Enter the following command to make the plugin executable.

   ```
   chmod +x /usr/local/bin/lightsailctl
   ```

1. Enter the following command to clear extended attributes for the plugin.

   ```
   xattr -c /usr/local/bin/lightsailctl
   ```

You are now ready to use the AWS CLI to push container images to your Lightsail container service. For more information, see [Push and manage container images](amazon-lightsail-pushing-container-images.md).

### Install the lightsailctl plugin on Linux


Complete the following procedure to install the Lightsail container services plugin on Linux.

1. Open a terminal window.

1. Enter the following command to download the lightsailctl plugin.
   + For the AMD 64-bit architecture version of the plugin:

     ```
     curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-amd64/lightsailctl" -o "/usr/local/bin/lightsailctl"
     ```
   + For the ARM 64-bit architecture version of the plugin:

     ```
     curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-arm64/lightsailctl" -o "/usr/local/bin/lightsailctl"
     ```

1. Enter the following command to make the plugin executable.

   ```
   sudo chmod +x /usr/local/bin/lightsailctl
   ```

   You are now ready to use the AWS CLI to push container images to your Lightsail container service. For more information, see [Push and manage container images](amazon-lightsail-pushing-container-images.md).

# Grant Lightsail container services access to Amazon ECR private repositories
ECR private repository access

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 AWS Region. 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](amazon-lightsail-container-services.md). For more information about Amazon ECR, see the [Amazon ECR User Guide](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html).

**Contents**
+ [Required permissions](#ecr-private-repos-permissions)
+ [Use the Lightsail console to manage access to private repositories](#ecr-private-repo-access-lightsail-console)
+ [Use the AWS CLI to manage access to private repositories](#ecr-private-repo-access-cli)
  + [Activate or deactivate the Amazon ECR image puller IAM role](#activate-ecr-puller-role)
  + [Determine if your Amazon ECR private repository has a policy statement](#identify-ecr-repo-policy-statement)
    + [Add a policy to a private repository that doesn't have a policy statement](#ecr-private-repo-add-policy-no-policy)
    + [Add a policy to a private repository that has a policy statement](#ecr-private-repo-add-policy-existing-policy)

## 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) 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.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "ManageEcrPrivateRepositoriesAccess",
            "Effect": "Allow",
            "Action": [
                "ecr:SetRepositoryPolicy",
                "ecr:DescribeRepositories",
                "ecr:DeleteRepositoryPolicy",
                "ecr:GetRepositoryPolicy"
            ],
            "Resource": "arn:aws:ecr:*:111122223333: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.

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.

------
#### [ JSON ]

****  

```
{
    "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](https://lightsail.aws.amazon.com/).

1. In the left navigation pane, choose **Containers**.

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-service-card.png)

1. Choose the **Images** tab.  
![\[Images tab in the container service management page of the Lightsail console\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-service-images-tab.png)

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-service-ecr-repos-section.png)

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-service-ecr-repos-selection.png)

   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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-service-ecr-repos-confirmation-modal.png)

1. 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 *\$1image tag\$1* with the tag of the image you want to deploy. For more information, see [Create and manage container service deployments](amazon-lightsail-container-services-deployments.md).  
![\[Next steps after adding an Amazon ECR private repository\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/container-service-ecr-repos-next-steps.png)

## 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](#ecr-private-repo-access-lightsail-console) 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](#activate-ecr-puller-role) section of this guide.

1. **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](#identify-ecr-repo-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](#ecr-private-repo-add-policy-no-policy) later in this guide.

   1. **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](#ecr-private-repo-add-policy-existing-policy) 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](https://docs.aws.amazon.com/cli/latest/reference/lightsail/update-container-service.html) 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](lightsail-how-to-set-up-and-configure-aws-cli.md).

1. Open a Command Prompt or Terminal window.

1. 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
     ```

1. 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](https://docs.aws.amazon.com/AmazonECR/latest/userguide/delete-repository-policy.html) in the *Amazon ECR User Guide*.

1. 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](#identify-ecr-repo-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](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-repository-policy.html) 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](https://docs.aws.amazon.com/AmazonECR/latest/userguide/get-set-up-for-amazon-ecr.html) in the *Amazon ECR User Guide*.

1. Open a Command Prompt or Terminal window.

1. 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](#ecr-private-repo-add-policy-no-policy) section later in this guide.  
![\[Response to the get-repository-policy command for a private repository that doesn't have a policy statement\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-no-policy-statement.png)
   + **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](#ecr-private-repo-add-policy-existing-policy) section later in this guide.  
![\[Response to the get-repository-policy command for a private repository that has a policy statement\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-existing-policy-statement.png)

### 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](#ecr-private-repo-access-lightsail-console) 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](https://docs.aws.amazon.com/cli/latest/reference/ecr/set-repository-policy.html) 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](https://docs.aws.amazon.com/AmazonECR/latest/userguide/get-set-up-for-amazon-ecr.html) in the *Amazon ECR User Guide*.

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

------
#### [ JSON ]

****  

   ```
   { 
     "Version":"2012-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.

1. 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).

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

1. Open a Command Prompt or Terminal window.

1. 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](amazon-lightsail-container-services-deployments.md).

   ```
   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](#ecr-private-repo-access-lightsail-console) 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](https://docs.aws.amazon.com/cli/latest/reference/ecr/set-repository-policy.html) 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](https://docs.aws.amazon.com/AmazonECR/latest/userguide/get-set-up-for-amazon-ecr.html) in the *Amazon ECR User Guide*.

1. Open a Command Prompt or Terminal window.

1. 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
   ```

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-existing-policy-copy-statement.png)

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-existing-policy-statement-json.png)

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-existing-policy-statement-json-edited.png)

1. Paste the following policy statement at the end of the text file.

------
#### [ JSON ]

****  

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

------

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-existing-policy-statement-json-completed.png)

1. 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).

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

1. Open a Command Prompt or Terminal window.

1. 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\]](http://docs.aws.amazon.com/lightsail/latest/userguide/images/ecr-set-policy-statement-response.png)

   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](amazon-lightsail-container-services-deployments.md).

   ```
   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
   ```