Layers

An image is a stack of layers, one per instruction

DockerfileThe layer each line adds, to scaleFROM python:3.12-slimWORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txtCOPY . .CMD ["python", "app.py"]125 MB: the base image0: a setting1 kB: one small file48 MB: the packages2 MB: your code0: a settingThe image: 175 MBAn image is a stack of read-only layers, one for each instruction that changes files.Each layer holds only the files that the instruction added or changed. Stacked in order, they makethe file system that the container will see. A running container adds one thin writable layer ontop, and that layer is thrown away when the container is removed.

Each instruction adds a layer. Stacked, they are the container's file system.

Layers · Going deeper · 1 of 2

Lab: build twice and watch the cache

TypeLook fordocker build -t web:1 .docker history web:1echo "# edit" >> app.pydocker build -t web:2 .docker images webevery step runs; the last line names web:1one row for each instruction, with its sizea change to the code onlyCACHED on every step before COPY . .two tags of nearly the same sizeLab: build an image twice and watch the cache.Work in a folder with the Dockerfile from the slide, an app.py and a requirements.txt (one line: flask).The second build finishes in a second or two, because only the last layer is new.

Build, read the history, change one file, build again.

ENTRYPOINT and CMD · Going deeper · 2 of 2

ENTRYPOINT is the program; CMD is its default arguments

In the DockerfileENTRYPOINT ["python", "app.py"]CMD ["--port", "8000"]the programits default argumentsYou runWhat starts as process 1Whydocker run webpython app.py --port 8000both defaults are useddocker run web --port 9000python app.py --port 9000words after the image name replace CMDdocker run --entrypoint sh webshENTRYPOINT is replaced and CMD is droppedargs: ["--port", "9000"]python app.py --port 9000Kubernetes: args replaces CMDcommand: ["sh"]shKubernetes: replaces ENTRYPOINT; CMD is droppedENTRYPOINT is the program. CMD is its default arguments. Kubernetes calls them command and args.With CMD alone, whatever follows the image name replaces the whole command. Write both in the exec form, with brackets:the shell form, CMD python app.py, wraps the program in /bin/sh -c, so the shell is process 1 and signals stop there.In a pod spec, setting command without args discards the image's CMD as well.

Kubernetes command replaces ENTRYPOINT. args replaces CMD.

The build cache

When one layer changes, all the later ones rebuild

You change one line of app.py and build again.All files copied firstFROM python:3.12-slimcachedCOPY . .again: 1 sRUN pip install -r ...again: 40 sThis build: about 41 secondsThe package list copied firstFROM python:3.12-slimcachedCOPY requirements.txt .cachedRUN pip install -r ...cachedCOPY . .again: 1 sThis build: about 1 secondWhen one layer changes, every layer after it is built again.A build reuses a layer from its cache if the instruction and the files it copies are unchanged.The first changed step breaks the chain. So put what changes rarely, such as installing packages,early, and what changes often, your own code, last.

Put what rarely changes first and your code last.

Tags and digests

A tag can move; a digest never does

ghcr.ioregistry/acme/webrepository:1.4tagor @sha256:9f2c...e41bdigest:1.4sha256:9f2c...built on MondayMondaysha256:41ab...built on FridayFriday: the same tag now names a different imageA tag is a label that can be moved. A digest is the fingerprint of the content itself.The digest is a hash of the image, so the same digest always means exactly the same bytes. A tagis only a name that the publisher may point somewhere new, and "latest" is just a tag that movesoften. Use clear version tags to release, and digests when a deployment must never change.

A tag is a movable label. A digest is the content's fingerprint.

Names and pull policy · Going deeper

What a short name stands for, and when a node pulls again

You writeThe full name it stands forWhat was filled innginxdocker.io/library/nginx:latestthe registry Docker Hub, and the tag latestacme/web:1.4docker.io/acme/web:1.4the registry onlyghcr.io/acme/web:1.4ghcr.io/acme/web:1.4nothingThe image in the podDefault imagePullPolicyWhat the kubelet does each time a container startsweb:latest, or no tagAlwaysasks the registry for the digest, and downloads only if it differsweb:1.4, or any other tagIfNotPresentuses the copy on the node if there is one, and asks nobodyweb@sha256:9f2c...IfNotPresentthe same; and a digest can never name different contentany, set by handNeveruses only a copy already on the node; without one: ErrImageNeverPullPush a new image under an old tag, and nodes that already hold that tag keep running the old one.With IfNotPresent a moved tag is noticed only by nodes that never pulled it, so one Deployment can run two differentimages under one name. Release under a new tag each time, or pin the digest. The default is fixed when the object iscreated: changing the tag to latest afterwards does not switch the policy to Always.

latest means Always. Any other tag means IfNotPresent.

Small images

The base image decides most of the size

python:3.121,020 MBpython:3.12-slim125 MBDebian with only what Python needspython:3.12-alpine50 MBthe tiny Alpine Linux✓less to download, so new servers start sooner✓fewer packages inside, so fewer security holes to patchThe base image decides most of the size. Choose the smallest one that still works.The same Python comes on three bases, drawn to scale. A larger base is convenient because everytool is there, and wasteful because it all ships to production. Keep build tools out of thefinal image with a multi-stage build, shown on the next page.

Same Python, three bases: 1,020, 125 and 50 megabytes.

Small images · Going deeper

Multi-stage builds: compile in one image, ship another

FROM golang:1.22 AS buildWORKDIR /srcCOPY . .RUN go build -o /out/server .FROM gcr.io/distroless/staticCOPY --from=build /out/server /serverENTRYPOINT ["/server"]stage 1: the whole Go toolchain, about 850 MBcompile the program herestage 2: a fresh, nearly empty basebring across only the finished programthe final image: about 12 MBA multi-stage build compiles in one image and ships another.Each FROM starts a new stage. Only the last stage becomes the image; earlier stages are workshopsthat are left behind. COPY --from lifts finished files out of a workshop. Compilers, tests andsource code never reach production, which makes the image small and gives attackers less to use.

Build in a workshop stage. Ship only the finished program.

Registries

Only the layers you lack are downloaded

Registry: web:1.4A server that ran web:1.3your code 2 MBpackages 48 MBpython:3.12-slim 125 MBpackages 48 MBpython:3.12-slim 125 MBalready here: nothing to downloadyour code 2 MBpull: 2 of 175 MBLayers are shared. A pull or a push moves only the layers the other side lacks.A registry is a store of images, such as Docker Hub, GitHub Container Registry or Amazon ECR.Because each layer is named by its digest, both sides can tell at once which ones they alreadyhold. Ten images built on one base keep a single copy of that base on disk.

Layers are shared. A pull moves only what is missing.

Inside a registry · Going deeper

A tag names an index; the index names one manifest for each platform

web:1.4a tagImage indexsha256:9f2c...e41bone entry per platformManifestlinux/amd64Manifestlinux/arm64Confighow to run it3 layersthe filesits own configand layersDocumentMedia typeWhat it holdsImage indexapplication/vnd.oci.image.index.v1+jsona list of manifests, each with an os and architectureManifestapplication/vnd.oci.image.manifest.v1+jsonthe digests of one config and of its layersConfigapplication/vnd.oci.image.config.v1+jsonhow to run it: entrypoint, cmd, env, userLayerapplication/vnd.oci.image.layer.v1.tar+gzipthe files one instruction added, as an archiveA digest names one small JSON document, and that document names everything else by digest.The runtime picks the manifest for its own platform, so one tag serves Intel servers and Arm laptops. An image built for oneplatform fails on the other with "exec format error". Build both: docker buildx build --platform linux/amd64,linux/arm64.

Index, manifest, config, layers: each named by its digest.

Lesson complete

You finished “Building and sharing images”

Nicely done.

Open in a new tab