Working with the Amazon Elastic Container Registry service in VS Code - AWS Toolkit for VS Code
Prerequisites1. Creating a Dockerfile2 . Build your image from your Dockerfile3. Create a new repository4. Push, pull, and delete images

Working with the Amazon Elastic Container Registry service in VS Code

You can access the Amazon Elastic Container Registry (Amazon ECR) service directly from the AWS Explorer in VS Code and use it to push a program image to an Amazon ECR repository. To get started, you need to do these steps:

  1. Create a Dockerfile that contains the information necessary to build an image.

  2. Build an image from that Dockerfile and tag the image for processing.

  3. Create a repository inside your Amazon ECR instance.

  4. Push the tagged image to your repository.

Prerequisites

Before you can use the Amazon ECR service feature of the Toolkit for VS Code, you must meet these prerequisites.

1. Creating a Dockerfile

Docker uses a file called a Dockerfile to define an image that can be pushed and stored on a remote repository. Before you can upload an image to an ECR repository, you must create a Dockerfile and then build an image from that Dockerfile.

Creating a Dockerfile

  1. Use the Toolkit for VS Code explorer to navigate to the directory where you want to store your Dockerfile.

  2. Create a new file that's called Dockerfile.

    Note

    VS Code could prompt you to select a file type or file extension. If this occurs, select plaintext. Vs Code has a "dockerfile" extension. However, we don't recommend you use it. This is because the extension might cause conflicts with certain versions of Docker or other associated applications.

Edit your Dockerfile using VS Code

If your Dockerfile has a file extension, open the context (right-click) menu for the file and remove the file extension.

After the file extension is removed from your Dockerfile:

  1. Open the empty Dockerfile directly in VS Code.

  2. Copy the contents of the following example into your Dockerfile:

    Example Dockerfile image template
    
FROM ubuntu:18.04

# Install dependencies
RUN apt-get update && \
 apt-get -y install apache2

# Install apache and write hello world message
RUN echo 'Hello World!' > /var/www/html/index.html

# Configure apache
RUN echo '. /etc/apache2/envvars' > /root/run_apache.sh && \
 echo 'mkdir -p /var/run/apache2' >> /root/run_apache.sh && \
 echo 'mkdir -p /var/lock/apache2' >> /root/run_apache.sh && \ 
 echo '/usr/sbin/apache2 -D FOREGROUND' >> /root/run_apache.sh && \ 
 chmod 755 /root/run_apache.sh

EXPOSE 80

CMD /root/run_apache.sh

    This is a Dockerfile that uses an Ubuntu 18.04 image. The RUN instructions update the package caches. Install software packages for the web server, and then write the "Hello World!" content to the document root of the web server. The EXPOSE instruction exposes port 80 on the container, and the CMD instruction starts the web server.

  3. Save your Dockerfile.

    Important

    Make sure that your Dockerfile doesn't have an extension attached to the name. A Dockerfile with extensions might cause conflicts with certain versions of Docker or other associated applications.

2 . Build your image from your Dockerfile

The Dockerfile that you created contains the information necessary to build an image for a program. Before you can push that image to your Amazon ECR instance, you must first build the image.

Build an image from your Dockerfile

  1. Use the Docker CLI or a CLI that's integrated with your instance of Docker to navigate into the directory that contains your Dockerfile.

  2. Run the Docker build command to build the image that's defined in your Dockerfile.

    
          docker build -t hello-world .

  3. Run the Docker images command to verify that the image was created correctly.

    docker images --filter reference=hello-world
    Example example output:
    
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
hello-world         latest              e9ffedc8c286        4 minutes ago       241MB
  4. Note

    This step isn't necessary to create or push your image, but you can see how the program image works when it's run.

    To run the newly built image use the Docker run command.

    docker run -t -i -p 80:80 hello-world

    The -p option that's specified in the preceding example maps the exposed port 80 on the container to port 80 of the host system. If you're running Docker locally, navigate to http://localhost:80 using your web browser. If the program ran correctly, a "Hello World!" statement is displayed.

    For more information about the Docker run command, see Docker run reference on the Docker website.

3. Create a new repository

To upload your image into your Amazon ECR instance, create a new repository where it can be stored in.

Create a new Amazon ECR repository

  1. From the VS Code Activity Bar, choose the AWS Toolkit icon.

  2. Expand the AWS Explorer menu.

  3. Locate the default AWS Region that's associated with your AWS account. Then, select it to see a list of the services that are through the Toolkit for VS Code.

  4. Choose the ECR + option to begin the Create new repository process.

  5. Follow the prompts to complete the process.

  6. After it's complete, you can access your new repository from the ECR section of the AWS Explorer menu.

4. Push, pull, and delete images

After you built an image from your Dockerfile and created a repository, you can push your image into your Amazon ECR repository. Additionally, using the AWS Explorer with Docker and the AWS CLI, you can do the following:

  • Pull an image from your repository.

  • Delete an image that's stored in your repository.

  • Delete your repository.

Authenticate Docker with your default registry

Authentication is required to exchange data between Amazon ECR and Docker instances. To authenticate Docker with your registry:

  1. Open a command line operating system that's connected to your instance of AWS CLI.

  2. Use the get-login-password method to authenticate to your private ECR registry.

    aws ecr get-login-password --region region | docker login --username AWS --password-stdin AWS_account_id.dkr.ecr.region.amazonaws.com
    Important

    In the preceding command, you must update both the region and the AWS_account_id to the information that's specific to your AWS account.

Tag and push an image to your repository

After you authenticated Docker with your instance of AWS, push an image to your repository.

  1. Use the Docker images command to view the images that you stored locally and identify the one you would like to tag.

    docker images
    Example example output:
    
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
hello-world         latest              e9ffedc8c286        4 minutes ago       241MB

  2. Tag your image with the Docker tag command.

    docker tag hello-world:latest AWS_account_id.dkr.ecr.region.amazonaws.com/hello-world:latest

  3. Push the tagged image to your repository with the Docker tag command.

    docker push AWS_account_id.dkr.ecr.region.amazonaws.com/hello-world:latest
    Example example output:
    
The push refers to a repository [AWS_account_id.dkr.ecr.region.amazonaws.com/hello-world] (len: 1)
e9ae3c220b23: Pushed
a6785352b25c: Pushed
0998bf8fb9e9: Pushed
0a85502c06c9: Pushed
latest: digest: sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b size: 6774

After your tagged image has been successfully uploaded to your repository, it's visible in the AWS Explorer menu.

Pull an image from Amazon ECR

  • You can pull an image to your local instance of Docker tag command.

    docker pull AWS_account_id.dkr.ecr.region.amazonaws.com/hello-world:latest
    Example example output:
    
The push refers to a repository [AWS_account_id.dkr.ecr.region.amazonaws.com/hello-world] (len: 1)
e9ae3c220b23: Pushed
a6785352b25c: Pushed
0998bf8fb9e9: Pushed
0a85502c06c9: Pushed
latest: digest: sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b size: 6774
Delete an image from your Amazon ECR repository

There are two methods for deleting an image from VS Code. The first method is to use the AWS Explorer.

  1. From the AWS Explorer, expand the ECRmenu

  2. Expand the repository that you want to delete an image from

  3. Choose the image tag associated with the image that you wish to delete, by opening the context menu (right-click)

  4. Choose the Delete Tag... option to delete all stored images associated with that tag

Delete an image using the AWS CLI

  • You can also delete an image from your repository with the AWS ecr batch-delete-image command.

    AWS ecr batch-delete-image \
      --repository-name hello-world \
      --image-ids imageTag=latest
    Example example output:
    
{
    "failures": [],
    "imageIds": [
        {
            "imageTag": "latest",
            "imageDigest": "sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b"
        }
    ]
}
Delete a repository from your Amazon ECR instance

There are two methods for deleting a repository from VS Code. The first method is to use the AWS Explorer.

  1. From the AWS Explorer, expand the ECR menu

  2. Choose the repository that you want to delete by opening the context (right-click) menu

  3. Choose the Delete Repository... option to the chosen repository

Delete an Amazon ECR repository from the AWS CLI

  • You can delete a repository with the AWS ecr delete-repository command.

    Note

    By default, you can't delete a repository that contains images. However, the --force flag allows this.

    
        AWS ecr delete-repository \
      --repository-name hello-world \
      --force
    Example example output:
    
{
    "failures": [],
    "imageIds": [
        {
            "imageTag": "latest",
            "imageDigest": "sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b"
        }
    ]
}