Appearance

Images and registries

Trace an application from a layered image to a node image pull.

What you will understand

  • Distinguish images from running containers
  • Read registry paths, tags, and digests
  • Diagnose why an image pull fails

Builds on: Containers are processes

Mental model: a packaged starting point

An image is a distribution artifact containing filesystem layers and configuration for a container. It is not a running process, a live container snapshot that updates automatically, or a complete copy of an operating system kernel. Starting two containers from one image creates separate runtime instances. Their writable changes are separate even if the runtime shares cached, read-only image layers on disk.

A build records filesystem changes in layers. Installing a dependency adds or modifies files relative to earlier layers. A later deletion can hide a file from the final filesystem without removing its bytes from an earlier layer. Therefore never place credentials into one build layer and “delete them later” as a security strategy. Build-time secret facilities and careful build context selection address a different problem from runtime Secret injection.

Image configuration includes defaults such as an executable, arguments, environment, and working directory. A Pod can override some of these. Inspect both the image and the Pod when an application starts with an unexpected command. Packaging a server does not prove that it will stay running or listen on the correct interface.

Image identity and writable changes

Separate image layers, a tag reference, and a container writable layer.

Storage viewStep 1 of 3
Publish layered contentThe image manifest describes immutable layer content and configuration. A repository tag points to a manifest identity.. web:training, active. Manifest digest, ready. Read-only layers, readyweb:training
web:trainingIn focus
Manifest digest
Manifest digestReady
Read-only layers
Read-only layersReady
web:trainingIn focus
Manifest digestReady
Read-only layersReady
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: runtime writes are mistaken for image changes
Publish layered content

The image manifest describes immutable layer content and configuration. A repository tag points to a manifest identity.

Read the complete visual sequence
  1. Publish layered content

    The image manifest describes immutable layer content and configuration. A repository tag points to a manifest identity.

  2. Create a container

    The runtime assembles the image filesystem and adds a writable layer for this container instance.

  3. Move a tag, preserve identity

    A tag may point somewhere new. A recorded digest still identifies the original content; the existing process does not silently switch.

Failure: runtime writes are mistaken for image changes

Failure: runtime writes are mistaken for image changes

  1. Write application state

    The process writes a file into its container filesystem, above the immutable image layers.

  2. Replace the container

    A replacement starts from the same image but receives a fresh writable layer. The old runtime file is absent.

  3. Choose the right state lifetime

    Use an explicit volume for state that must follow a Pod or outlive it. Rebuilding an image and mounting storage solve different problems.

About this model

A single-platform image is shown; registries can instead return a multi-platform index.

Walkthrough: read the full image reference

In registry.k8s.io/pause:3.10, registry.k8s.io is the registry hostname, pause is the repository path, and 3.10 is a tag. A tag is a human-friendly reference that registry operators may move to another image. A digest identifies content using a hash, for example a complete sha256 digest obtained from your trusted build or registry. Do not copy an invented digest into a manifest and expect a pull to succeed.

A multi-platform image index can refer to different image manifests for different operating systems or CPU architectures. A tag that works on one workstation may still fail on a differently provisioned node. Validate the supported platform and choose the digest appropriate to your release process. Digest pinning improves identity and repeatability; it does not by itself establish that the producer is trustworthy or that the software has no vulnerabilities.

apiVersion: v1
kind: Pod
metadata:
  name: image-demo
spec:
  containers:
    - name: web
      # Training tag: use your verified digest for repeatable releases.
      image: nginx:1.27.5
      # Reuse this exact reference's local image when available.
      imagePullPolicy: IfNotPresent
      ports:
        - containerPort: 80

Save this as image-demo.yaml in the module lab. containerPort describes a port; it neither starts a listener nor publishes that port outside the Pod. The container image starts nginx, which supplies the actual server.

kubectl apply -f image-demo.yaml
kubectl get pod image-demo -o wide
kubectl describe pod image-demo
# Show the image identity reported for the running container.
kubectl get pod image-demo -o jsonpath='{.status.containerStatuses[0].imageID}'

A successful result progresses toward Running, with a runtime-reported image ID. Its formatting may differ by runtime. Compare it with the requested reference rather than assuming the status field repeats the original tag exactly.

The node pulls the image

Follow a kubelet/runtime image request through registry resolution and cache reuse.

Flow viewStep 1 of 3
Pod names an imageThe assigned Pod asks for nginx:1.27.5. The kubelet delegates image work through the container runtime interface.. Pod image reference, active. Kubelet, active. Container runtime, idlePod image reference
Pod image referenceIn focus
Kubelet
KubeletIn focus
Container runtime
Container runtimeContext
Pod image referenceIn focus
KubeletIn focus
Container runtimeContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: registry refuses the pull
Pod names an image

The assigned Pod asks for nginx:1.27.5. The kubelet delegates image work through the container runtime interface.

Read the complete visual sequence
  1. Pod names an image

    The assigned Pod asks for nginx:1.27.5. The kubelet delegates image work through the container runtime interface.

  2. Resolve and reuse content

    When a pull is required, the runtime resolves the manifest and downloads only missing layers. Cached content can still be reused with Always.

  3. Start the executable

    After image preparation and sandbox setup, the runtime creates the container. The required image must be available, either from a permitted local cache or a pull; that does not establish application health.

Failure: registry refuses the pull

Failure: registry refuses the pull

  1. Invalid image reference

    The Pod object exists, but its image tag cannot be resolved at the registry.

  2. Retry with backoff

    The kubelet reports image pull failure and delayed retry. No application process exists to produce application logs.

  3. Inspect the concrete reason

    Describe the Pod and correct the reference or credentials. Do not treat this as a liveness or application exit problem.

About this model

Registry access is from the worker runtime; one node and one image are shown.

Practice: separate download from execution

The kubelet asks the container runtime to ensure the image is available. The runtime contacts the registry when required, resolves manifests, checks its layer cache, and downloads missing content. Always requires resolving the reference when starting a container; cached layers can still avoid downloading identical data. IfNotPresent can reuse a local image. Neither policy guarantees automatic updates to already running containers when someone moves a tag.

In a disposable lab, change the reference to an intentionally nonexistent tag and inspect Pod events. The API can accept a perfectly valid object even though the registry cannot supply its image. ImagePullBackOff describes delayed retries after pull failures, not an application crash. Check the underlying event for missing tags, authorization, DNS, certificates, connectivity, or platform incompatibility. For private images, image pull credentials must be available in the Pod’s namespace using supported credential mechanisms. Avoid printing credential objects while debugging.

Pitfalls

A developer’s successful local pull does not establish that a cluster node has the same network route, architecture, cache, or credentials. Resolve failures from the node/runtime’s point of view. A cached mutable tag can also cause replicas to use unexpected contents across nodes; a controlled rollout with an immutable image identity is easier to explain.

Check your understanding

A new image is pushed under the same tag. Will every existing Pod immediately run it?

No. Existing containers keep running their current image. A new container start may resolve or reuse the reference according to its pull policy and cache. Changing the Pod template to a verified new digest produces an explicit release identity and, with a Deployment, triggers a managed rollout. Moving a registry tag is not a Kubernetes rollout command.

Next, trace how a client reaches the process packaged in that image. Practice image inspection and deliberate pull failure in the module lab.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.