Storing images: ECR

So QuickCart needs a place for images that:

• only QuickCart can push to, and AWS can pull from;
• never lets v1 quietly change meaning;
• checks each image for known security problems.

That place is ECR.

A registry is a server that stores images, so that any machine allowed to reach it can download them. ECR, Elastic Container Registry, is AWS’s registry. It lives inside your AWS account, it’s private by default, and ECS and EKS can pull from it without any extra setup.

The words

The image URI is just the registry, the repository and the tag joined together. Docker reads the part before the first / to know which server to talk to. That’s why a local image called order-service:v1 has to be given its full ECR name before you can push it.

Tags move. Digests don’t.

A tag is a name a person chose. In an ordinary registry, you can push a different image with the same tag, and the tag simply moves to it. The old image loses its name.

A digest is calculated from the image’s bytes. Change one byte and the digest changes. So a digest always means exactly one image.

Immutable tags

ECR can make a repository’s tags immutable. Once v1 exists, ECR refuses any push that would move it. Every tag then means one build forever, and a rollback to v1 is always exact.

Scanning

ECR can scan each image for known vulnerabilities — published security problems in the software inside it, such as an old version of a system library.

Scan on push means each image is scanned as soon as it arrives. Results are grouped by severity: Critical, High, Medium, Low and Informational. A scan doesn’t block anything by itself. It tells you, and your pipeline decides what to do about it — the continuous integration lesson does that.

Lifecycle policies

ECR keeps every image you push, and storage is billed per GB. A lifecycle policy is a set of rules that expire old images automatically. QuickCart uses two:

Logging in is different

Docker needs a username and password for a private registry. ECR doesn’t use a fixed password. Instead, the AWS CLI asks AWS for a temporary password that lasts 12 hours, using the login you already have in your terminal. You hand that password to Docker, and Docker remembers it until it expires.

The console has no way to push an image, so logging in and pushing are the parts of this lesson that happen in the terminal.

Follow the tag v1 through five steps: push a build, deploy it, push a fix with the same tag, lose a task, then roll back. Play it with Mutable tags first, then again with Immutable.

What to notice: with mutable tags, nothing failed and nothing warned. Every push, every task start and the rollback all “worked”. The only sign of trouble was two tasks running different code under one name — and nobody was looking at digests.

Pennies — ECR storage is about $0.10 per GB each month in us-east-1, and this image is under 100 MB. Basic scanning is free. Prices change, so check the ECR pricing page if you want the exact number.

You’ll create a private repository with immutable tags, push QuickCart’s order service to it, watch ECR refuse an overwrite, and add a lifecycle policy. About 25 minutes.

You need Docker Desktop running, the AWS CLI with a working login (Set up your computer), and the order-service folder from Writing a Dockerfile: app.py, requirements.txt and Dockerfile.

Open a terminal in that folder:

cd order-service

1. Create the repository

   Check the region selector at the top right of the console says N. Virginia (us-east-1).

   AWSIn the AWS console: Amazon ECR→Private registry→Repositories→Create repository

   Field	Enter
   Repository name	quickcart-orders
   Image tag mutability	Immutable
   Encryption configuration	AES-256 — the default

   If the page has an Image scan settings section, turn Scan on push on. Then choose Create.

   Newer versions of the console set scanning for the whole registry instead. If there’s no scan setting on this page, go to

   AWSIn the AWS console: Amazon ECR→Private registry→Settings→Scanning

   and choose Basic scanning, with a scan on push filter of *, so every repository is scanned when an image arrives.
   You should see

   quickcart-orders in the list, with Tag immutability: Immutable. The URI column shows 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders, with your own account ID at the start. Copy it — you’ll use it in every command below.

2. Log Docker in to ECR

   This is the one step in the lesson with a pipe. It can’t be done in the console. Replace 111122223333 with your account ID — it’s the number at the start of the URI you just copied.

   TerminalCopy

   aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com

   Part	What it means
   aws ecr get-login-password	ask AWS for a temporary ECR password, using your terminal’s AWS login. It prints the password and nothing else
   --region us-east-1	for the registry in this region. Each region has its own registry
   |	a pipe: instead of printing the password on screen, pass it straight in as the input of the next command
   docker login	log Docker in to a registry and remember the password
   --username AWS	ECR’s username is always the word AWS
   --password-stdin	read the password from the pipe. So it never appears on screen, in your command history, or in the list of running processes, where --password would put it
   111122223333.dkr.ecr.us-east-1.amazonaws.com	the registry to log in to: your account ID, dkr.ecr, then the region

   You should see

   Login Succeeded

   The login lasts 12 hours. After that, run this command again. Docker may also print a warning about where it stores the password; that’s normal.

3. Build the image for AWS

   TerminalCopy

   docker build --platform linux/amd64 --provenance=false -t order-service:v1 .

   Part	What it means
   docker build	build an image from the Dockerfile in this folder
   --platform linux/amd64	build for Intel and AMD processors, which is what this course’s Fargate tasks use. A Mac with an Apple chip would otherwise build for ARM
   --provenance=false	don’t attach a build record to the image. Without this, Docker’s builder (BuildKit) pushes an image index — a list holding your image plus a record — and ECR shows it as extra untagged rows
   -t order-service:v1	name the image order-service, tag v1
   .	use the files in this folder

   The last lines look like

    => exporting to image
    => => naming to docker.io/library/order-service:v1

   The exact lines vary with your Docker version. The name at the end is what matters.

4. Give it its ECR name

   Docker pushes an image to whatever server is named at the start of the image’s name. So give it a second name that starts with your registry:

   TerminalCopy

   docker tag order-service:v1 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v1

   Part	What it means
   docker tag	give an existing image another name. Nothing is copied
   order-service:v1	the image you just built
   111122223333.dkr.ecr.us-east-1.amazonaws.com	your registry: where it will be pushed
   /quickcart-orders	the repository inside it
   :v1	the tag

   It prints nothing when it works.

5. Push it

   TerminalCopy

   docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v1

   Part	What it means
   docker push	upload an image to the registry named at the start of its name
   111122223333.dkr.ecr.us-east-1.amazonaws.com	the registry to upload to, read from the start of the name
   /quickcart-orders:v1	the repository and tag inside it

   You should see lines like these

   The push refers to repository [111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders]
   5f70bf18a086: Pushed
   e3c9b0a7d41f: Pushed
   v1: digest: sha256:7c4e9a1fb03d6e2a8f5c1b9d0e7a3f6c2b8d4e1a9f0c7b3e6d2a5f8c1e4b7d0a size: 1994

   There’s one Pushed line per layer, and your IDs, digest and size will differ. The last line is the one to keep: that digest is the image’s fingerprint.

6. Look at the image and its scan

   AWSIn the AWS console: Amazon ECR→Private registry→Repositories→quickcart-orders

   You should see

   One row: tag v1, artifact type Image, a push time, a size of around 50 MB, and the same digest that docker push printed. After a minute, the vulnerability column fills in. Choose the digest or the tag to see the findings, grouped by severity.

   A slim base image usually has a few Low or Medium findings and ideally no Critical ones. Findings in the base image are fixed by rebuilding on a newer base image, not by changing your code.

7. Try to overwrite v1

   Leo’s quick fix: the same app, built again with a different version label.

   TerminalCopy

   docker build --platform linux/amd64 --provenance=false --build-arg APP_VERSION=v1-fix -t order-service:v1-fix .

   Part	What it means
   docker build	build the image again
   --platform linux/amd64	for AWS’s processors, as before
   --provenance=false	one plain image, as before
   --build-arg APP_VERSION=v1-fix	stamp it with a different version, so it’s a different image with a different digest
   -t order-service:v1-fix	its local name
   .	this folder

   Now give it the name v1 in ECR — the mistake from the story:

   TerminalCopy

   docker tag order-service:v1-fix 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v1

   Part	What it means
   docker tag	give an image another name
   order-service:v1-fix	the new build
   111122223333.dkr.ecr.us-east-1.amazonaws.com	your registry
   /quickcart-orders:v1	the tag that already exists in ECR

   TerminalCopy

   docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v1

   Part	What it means
   docker push	try to upload it as v1

   ECR refuses

   tag invalid: The image tag 'v1' already exists in the 'quickcart-orders' repository and cannot be overwritten because the repository is immutable.

   That refusal is the point. On a mutable repository this push would have worked, silently.

8. Push the fix properly, as v2

   TerminalCopy

   docker tag order-service:v1-fix 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v2

   Part	What it means
   docker tag	give the fix a new, unused tag
   quickcart-orders:v2	the next version

   TerminalCopy

   docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v2

   Part	What it means
   docker push	upload it as v2

   Most layers are already there

   The push refers to repository [111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders]
   5f70bf18a086: Layer already exists

   Only the layers that changed are uploaded. The repository now shows two tags, v1 and v2, with two different digests.

9. Pull by digest

   In the console, copy the full digest of v1 — it starts with sha256:. Then ask for the image by that fingerprint instead of by its tag:

   TerminalCopy

   docker pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders@DIGEST

   Part	What it means
   docker pull	download an image
   quickcart-orders	from this repository
   @	followed by a digest, instead of : followed by a tag
   DIGEST	replace this with the digest you copied, including sha256:

   You should see

   Docker reports the digest and that the image is downloaded or already up to date. Whatever happens to any tag in future, this exact address always gives this exact image.

10. Add a lifecycle policy

    AWSIn the AWS console: Amazon ECR→Private registry→Repositories→quickcart-orders→Lifecycle policy→Create rule

    Create the first rule:

    Field	Enter
    Rule priority	1
    Rule description	Expire untagged images after 7 days
    Image status	Untagged
    Match criteria	Since image pushed
    Count number	7, unit days

    Save it, choose Create rule again, and create the second:

    Field	Enter
    Rule priority	2
    Rule description	Keep the newest 20 version tags
    Image status	Tagged (prefix matching)
    Tag prefixes	v
    Match criteria	Image count more than
    Count number	20

    Save it. Behind the form, ECR stores the rules as JSON. You can see it on the repository’s lifecycle policy page, and this is what you would write in Terraform later:

    lifecycle-policy.jsonCopy

    {
      "rules": [
        {
          "rulePriority": 1,
          "description": "Expire untagged images after 7 days",
          "selection": {
            "tagStatus": "untagged",
            "countType": "sinceImagePushed",
            "countUnit": "days",
            "countNumber": 7
          },
          "action": { "type": "expire" }
        },
        {
          "rulePriority": 2,
          "description": "Keep the newest 20 version tags",
          "selection": {
            "tagStatus": "tagged",
            "tagPrefixList": ["v"],
            "countType": "imageCountMoreThan",
            "countNumber": 20
          },
          "action": { "type": "expire" }
        }
      ]
    }

    Setting	What it does
    rulePriority	the order rules are checked in. Lower numbers first, and each must be different
    description	a note for people. ECR ignores it
    tagStatus	which images the rule looks at: untagged, tagged (then give prefixes or patterns) or any
    tagPrefixList	with tagged: only images with a tag starting with one of these
    countType	sinceImagePushed means “older than”; imageCountMoreThan means “more than this many”
    countUnit and countNumber	how many days, or how many images
    action	what to do with matching images. expire is the only choice, and it deletes them

    You should see

    Two rules on the lifecycle policy page. Nothing is deleted yet: you have only two images, both tagged and both new. ECR applies the rules on its own schedule, usually within a day.

11. Clean-up step: Clean up

    If you’re going on to ECS on Fargate, keep the repository and the v1 image. The next lesson runs them, and its clean-up deletes the repository. It costs pennies in the meantime.

    Otherwise, delete the repository and every image in it:

    AWSIn the AWS console: Amazon ECR→Private registry→Repositories→tick quickcart-orders→Delete

    Type delete to confirm, and choose Delete.

    Then remove the local copies from your computer. Each name you gave an image is removed separately:

    TerminalCopy

    docker image rm order-service:v1 order-service:v1-fix 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v1 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders:v2

    Part	What it means
    docker image rm	remove images from this machine. It doesn’t touch ECR
    order-service:v1 and order-service:v1-fix	the two local names
    the two quickcart-orders names	the ECR names you added with docker tag

    You should see

    One Untagged: line per name, then Deleted: lines once the last name for an image is gone. The repository is gone from the ECR console.