Lesson 2 of 8 in Containers with Docker
Images, layers and tags
An image is a read-only package of files plus default settings, stored as a stack of layers. A container is an image with a thin writable layer on top, and a tag is a movable name that points at an image.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: What a container actually is
The problem this solves
To run the same app on any machine you need to ship its files and its whole environment together: the runtime, the libraries and your code. Copying a folder is not enough, and installing everything by hand each time invites drift.
The package also needs to be cheap to store and move. Ten apps built on the same base system should not each carry their own copy of it.
Images solve both. They are built from layers that can be shared between images, and they are identified by names you can pull from a registry, which is a server that stores images.
How it works
- Data
- Runs code
You pull an image from a registry, and each container started from it shares those read-only layers while keeping its own writable layer.
- Registry to Image: 1 docker pull
- Image to Container 1: 2 docker run
- Image to Container 2: 2 docker run
- Data
- Runs code
A base layer, a packages layer and an app layer are read-only and shared, and a container adds a writable layer that disappears with it.
- Base layer to Packages layer: 1 adds on top
- Packages layer to App layer: 2 adds on top
- App layer to Writable layer: 3 container adds
An image is built in steps, and each step that changes files produces a layer holding only that change. Layers are identified by a content hash, so two images that start from the same base reuse the same base layer on disk and in downloads.
Layers are read-only. When you start a container, Docker adds one thin writable layer on top. Anything the container writes goes there. When you remove the container, that layer is deleted, which is why changes made inside a container do not become part of the image.
A name like nginx:1.27 is a repository (nginx) plus a tag (1.27). A tag is a label that can be moved to point at a newer image, and latest is just a tag with that name, not a promise of newest. A digest such as alpine@sha256:<digest> names exactly one image and never moves.
Try it yourself
These commands download a very small image and only read information about it.
- 1Pull an image
docker pull alpine:3
Docker downloads the layers it does not already have. For a tiny image there is often just one.
- 2List images, with their digests
docker image ls --digests alpine
The digest column is the immutable identity. The tag next to it can later point at a different digest.
- 3Read the layer history
docker history alpine:3
Each row is a step in the build. Rows with a size added files. Rows showing 0B only changed settings.
- 4Prove that changes do not stay
docker run --name scratch alpine sh -c 'echo hi > /note.txt' docker rm scratch docker run --rm alpine cat /note.txt
The last command fails because
/note.txtlived in the first container's writable layer, whichdocker rmdeleted.
What breaks, and where to look
Unable to find image 'nginxx:latest' locally ... pull access denied for nginxx, repository does not exist or may require 'docker login'
- WHY IT HAPPENS
- Docker searched the registry and found nothing under that name. Usually a typo, a missing owner prefix like
owner/name, or a private image you are not logged in for. - CHECK FIRST
- Re-read the name character by character, search for it on the registry's website, and run
docker loginif it is private.
manifest for alpine:3.99 not found: manifest unknown
- WHY IT HAPPENS
- The repository exists but that tag does not. Tags can be removed or never existed.
- CHECK FIRST
- Look up the real tags on the image's registry page, or use a tag you know exists such as
alpine:3.
A file you created or a package you installed inside a running container is gone after you remove it and start a new one.
- WHY IT HAPPENS
- Changes went into the container's writable layer, and the image was never changed. New containers start from the original image again.
- CHECK FIRST
- Run
docker diff <container>before removing it to see what changed. To keep changes, put them in a Dockerfile, or store data in a volume.
When not to use this
- Pulling
latestin anything you need to reproduce is risky because the tag moves. Pin a specific version tag, or a digest when exactness matters. - An image is a snapshot of files, not of a running machine. If you want to preserve live state such as a database's data, use a volume, covered later in this topic.
Check yourself
Why do ten images built on the same base not take ten times the space?
They share the identical base layers, which are stored and downloaded once.
Where does a file written inside a running container go?
Into that container's thin writable layer, which is deleted when the container is removed.
How is a digest different from a tag?
A tag is a movable label and may later point at a different image. A digest names exactly one image forever.
Keep going
Lesson 40 of 92 in the DevOps path