Using Amazon Container Registry Service

In an earlier article, we looked at four hosted Docker repositories: DockerHub, Quay.io, Artifactory and Google Container Registry. Since that article was published, Amazon has released their hosted container registry service. Many Docker and Rancher users host their infrastructure on Amazon Web Services (AWS). So, we wanted to provide an overview of setting up and using Amazon’s container registry service and compare it with other tools we looked at earlier.

Registry Setup

1. Install AWS CLI: To setup an Amazon Container Registry (ACR), first make sure you have a new version of the AWS CLI installed and configured. This article was tested using *version 1.10.1. * You can verify your installed version by running:

aws --version
aws-cli/1.10.1 Python/2.7.10 Darwin/15.3.0 botocore/1.3.23

2. Create a Repository: The next step is to create a repository. This can be done using the command below where project-name and repository name can be selected as needed. Please take note of the project and repository name as you will need this in later steps.

aws ecr create-repository --repository-name project-name/repository-name

3. Login to the AWS Registry: Once you have created a registry, you need to log your docker client into the AWS Registry service using the following command. Note, if you are running infrastructure in a region other than us-east-1, you will need to either configure your AWS client or override the default region using the --region switch.

$(aws ecr get-login)
WARNING: login credentials saved in /Users/XXXXXXXXX/.docker/config.json
Login Succeeded

**4. Create a Policy Document: ** The registry service allows very fine grained permissions management which ties into Amazon’s IAM service. To setup permissions, copy the following text into a file called repository-policy.json. In the file, replace 000000000000 with your AWS Account id. If you don’t know your Account ID browse to AWS Support and the ID will be in the top right corner. In the example file, we are giving permissions to one specific IAM user and one specific role. You can add as many roles and users to the list as your need. If you would like to give all users in the AWS account permissions, then you may use \“Principal\” : \”*\“, instead of the array below. Secondly, the list of permissions in the Action section below contain all possible permissions. You may specify a subset of permissions if you would like to create a more constrained access profile. Lastly, we are creating a policy with a single statement block. You may create multiple statement blocks to give different levels of permissions to different users.

{
    "Version": "2008-10-17",
    "Statement": [{
        "Sid": "PolicyStatement",
        "Effect": "Allow",
        "Principal": {
            "AWS": [
                "arn:aws:iam::000000000000:role/SOME-ROLE",
                "arn:aws:iam::000000000000:user/SOME-USER"
            ]
        },
        "Action": [
            "ecr:GetDownloadUrlForLayer",
            "ecr:BatchGetImage",
            "ecr:BatchCheckLayerAvailability",
            "ecr:PutImage",
            "ecr:InitiateLayerUpload",
            "ecr:UploadLayerPart",
            "ecr:CompleteLayerUpload",
            "ecr:DescribeRepositories",
            "ecr:GetRepositoryPolicy",
            "ecr:ListImages",
            "ecr:DeleteRepository",
            "ecr:BatchDeleteImage",
            "ecr:SetRepositoryPolicy",
            "ecr:DeleteRepositoryPolicy"
        ]
    }]
}

5. Apply Policy: To apply the policy you created, use the command specified below. You are not setup and can push and pull containers from the AWS Container registry.

aws ecr set-repository-policy                      \
    --repository-name project-name/repository-name \
    --policy-text "$(cat repository-policy.json)"

Using the AWS Registry Service

To start using the service, you follow the same steps as any other private docker registry i.e. re-tag your container and push to the repository. For example, in the snippet below we are building a container called container-tag, re-tagging with the Amazon Registry Service URL and our repository name from earlier and then pushing to the Amazon Registry Service. Note in the commands below, you must once again replace 000000000000 with your AWS Account ID.

docker build -t container-tag .
docker tag -f container-tag \
    000000000000.dkr.ecr.us-east-1.amazonaws.com/project-name/repository-name:version
docker push 000000000000.dkr.ecr.us-east-1.amazonaws.com/project-name/repository-name:version

When you would like to pull this container onto another host you must run \$(aws ecr get-login) and then use docker pull with the AWS Registry Service URL.

$(aws ecr get-login)
docker pull 000000000000.dkr.ecr.us-east-1.amazonaws.com/project-name/repository-name:version

Using the AWS Registry Service with Rancher

If you would like to use the ECR with Rancher browse to Infrastructure > Registries and select *Add Registry *and select Custom as the registry type. In the resulting form your will be asked to enter the Address, Email, Username and Password. The address corresponds to your Amazon Account ID and region e.g. (000000000000.dkr.ecr.us-east-1.amazonaws.com). The email field will always be set to none and the username will be set to AWS. The password can be retrieved using the aws ecr get-login command and looking for the -p parameter in the output. You can use the following command to get the password string. Now you can use the fully qualified name of the image (e.g. 000000000000.dkr.ecr.us-east-1.amazonaws.com/project-name/repository-name:version) in Rancher to pull images from ECR.

aws ecr get-login | cut -d ' ' -f 6

Note that because access to ECR is controlled with AWS IAM. An IAM user must request a temporary credential to the registry using the AWS API. This temporary credential is then valid for 12 hours. To do this you can use the image objectpartners/rancher-ecr-credentialsto refresh the credentials periodically. The docker-compose.yaml file to setup the credentials service is shown below.

ECRCredentials:
  environment:
    AWS_REGION: us-east-1
    AWS_ACCESS_KEY_ID: XXXXXXXXXXXXXXXXXXXX
    AWS_SECRET_ACCESS_KEY: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  labels:
    io.rancher.container.pull_image: always
    io.rancher.container.create_agent: 'true'
    io.rancher.container.agent.role: environment
  tty: true
  image: objectpartners/rancher-ecr-credentials
  stdin_open: true

Evaluation

When we compared the four hosted registry services earlier, we use four dimensions to evaluate their performance: Workflow, Authentication/Authorization, Availability/Performance and Pricing. We will use the same to evaluate Amazon Container Registry.

In terms of workflow, the registry offer basic features and does not integrate any automated builds or detailed metrics for repository usage. This does mean that you will need to setup and manage continuous integration. This can be an issue if you were looking to offload this task. However, you probably already run CI tools such as Jenkins or Bamboo for continuous integration of your code. It should be trivial to integrate the registry service with your CI tool. Furthermore, fully scripted command-line access to create and manage repositories is a powerful feature.

Amazon offers very detailed and comprehensive support for authentication and authorization through their IAM service. If you are not already versed in IAM usage, then setting up fine grained policies and roles can be daunting. However, this is a hurdle you have to get over once. If you are running infrastructure in AWS, being well versed in IAMs usage is a pretty much a prerequisite.

The Container registry service uses Amazon s3 which promises 4 nines of up-time and 11 nines for data durability. This is well within reasonable limits for most commercial applications. As for cost, you pay the standard AWS rates for storage and network transfer. This is ten cents per gigabyte per month for storage and nine cents per gigabyte for egress traffic from Amazon’s network. Transfers to in-region Amazon infrastructure is free. This means for most use-cases, the cost of the service will be negligible compared to other infrastructure costs.

If you’re interested in learning more about Docker, Rancher, Kubernetes or anything else, join us for our monthly online meetups, where we talk about the latest on using containers to deploy applications.