Stage 4 · Provision

Image Internals & Advanced Builds

OCI Image Layout

Inspect manifests, config JSON, layer tarballs, media types, and multi-architecture indexes with skopeo.

8 min readDocker & ContainersProvision

Image Layout Overview

An OCI image is a content-addressable store of objects. The layout consists of a blobs directory containing all content (layers, configs, manifests), each identified by its SHA256 digest. A manifest list points to platform-specific manifests. Each manifest references an image config and layers.

OCI image layout on disk


# Save an image as a tar
docker save nginx:alpine -o nginx-alpine.tar

# Extract and examine the layout
mkdir nginx-layout && tar xf nginx-alpine.tar -C nginx-layout
ls nginx-layout/

# Layout structure:
# nginx-layout/
#   manifest.json
#   <sha256-blob>
#   <sha256-blob>
#   ...
#   repositories

docker save exports the image in Docker's format. The manifest.json lists all layers and the config. Each layer is a tar archive identified by its SHA256 hash.

Inspecting Manifests

Image manifest structure


{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "digest": "sha256:abc123...",
    "size": 582
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.container.image.layer.v1.tar+gzip",
      "digest": "sha256:def456...",
      "size": 3245678
    },
    {
      "mediaType": "application/vnd.docker.container.image.layer.v1.tar+gzip",
      "digest": "sha256:ghi789...",
      "size": 1234567
    }
  ]
}

The manifest is the root document. It references the config (metadata) and layers (filesystem changes). Each reference includes media type, digest, and size. The digests are SHA256 hashes of the compressed content.

Config JSON

Inspecting image config


# Get the image config digest
docker inspect --format '{{index .RepoDigests 0}}' nginx:alpine

# Pull the config blob
# The config contains architecture, OS, entrypoint, env, etc.

# Inspect config with crane
crane config nginx:alpine | jq

# Inspect config with docker
docker inspect nginx:alpine --format '{{json .Config}}' | jq

The config JSON contains the image's architecture, OS, entrypoint, CMD, environment variables, working directory, labels, and exposed ports. It is the metadata that tells Docker how to run the image.

Layer Structure

Examining layers


# List layers with sizes
docker history nginx:alpine

# Example output:
# IMAGE          CREATED      SIZE    COMMAND
# abc123         2 days ago  0B     CMD ["nginx" "-g" "daemon off;"]
# def456         2 days ago  1.2kB  STOPSIGNAL SIGQUIT
# ghi789         2 days ago  4.62kB COPY nginx.conf /etc/nginx/nginx.conf
# jkl012         2 days ago  56.2MB RUN apk add --no-cache nginx
# mno345         2 weeks ago 7.34MB /bin/sh -c #(nop) ADD file:abc in /

# Extract a layer to examine its contents
docker export $(docker create nginx:alpine) | tar -tf - | head -20

Each layer represents filesystem changes. The bottom layer is the base image. Each subsequent layer adds, modifies, or deletes files. Layer sizes tell you where the bloat is.

Multi-Arch Indexes

Multi-architecture manifest lists


# Inspect a multi-arch manifest
docker manifest inspect nginx:alpine

# Output shows all architectures:
# amd64, arm64, arm/v7, arm/v6, 386, ppc64le, s390x

# Pull the correct architecture automatically
docker pull nginx:alpine
# Docker selects the platform matching your host

# Pull a specific architecture
docker pull --platform linux/arm64 nginx:alpine

A manifest list (index) contains platform-specific manifests. Docker automatically pulls the correct architecture. --platform overrides the automatic selection for cross-platform testing.

Using skopeo

skopeo for image inspection


# Install skopeo
brew install skopeo  # macOS

# Inspect image manifest
skopeo inspect docker://nginx:alpine | jq

# List tags for an image
skopeo list-tags docker://docker.io/library/nginx

# Copy images between registries
skopeo copy docker://nginx:alpine docker://myregistry.com/nginx:alpine

# Inspect image with specific OS/arch
skopeo inspect --override-os linux --override-arch arm64 docker://nginx:alpine

skopeo operates on images without pulling them. It can inspect, copy, and compare images across registries. It is invaluable for examining remote images and migrating between registries.

Use crane for fast image operations

crane is a tool for interacting with container registries at the OCI level. It is faster than docker for pulling, pushing, and inspecting images. Use crane digest, crane config, crane manifest for quick inspections.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.