Lesson 2 of 8 in Containers with Docker

Images, layers and tags

Core8 min

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

From registry to running containers
From registry to running containersYou pull an image from a registry, and each container started from it shares those read-only layers while keeping its own writable layer.1 docker pull2 docker run2 docker runRegistryDocker Hub, etc.Imageread-only layersContainer 1own writable layerContainer 2own writable layer
  • 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.

  1. Registry to Image: 1 docker pull
  2. Image to Container 1: 2 docker run
  3. Image to Container 2: 2 docker run
Layers stack up, and only the top one is writable
Layers stack up, and only the top one is writableA 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.1 adds ontop2 adds ontop3 containeraddsBase layerOS filesPackages layerruntime, librariesApp layeryour codeWritable layerlost on docker rm
  • 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.

  1. Base layer to Packages layer: 1 adds on top
  2. Packages layer to App layer: 2 adds on top
  3. 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.

  1. 1
    Pull an image
    docker pull alpine:3

    Docker downloads the layers it does not already have. For a tiny image there is often just one.

  2. 2
    List 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.

  3. 3
    Read 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.

  4. 4
    Prove 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.txt lived in the first container's writable layer, which docker rm deleted.

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 login if 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 latest in 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.

Lesson 40 of 92 in the DevOps path

Search

Search cheat sheets and projects