Agent Skills: Docker Knowledge Patch

Docker Knowledge Patch

Baseline: Docker Engine 24.x and Compose 2.x. Covered range: Engine 25.0.0 through 29.3, Engine API v1.44 through v1.55, Compose 5.0.0 through 5.3.0, Buildx 0.30.0 through 0.35.0, BuildKit 0.28.0, and Dockerfile 1.22.0.

Included versioned batches: 25.0.0, 26.0.0, 27.0.1, 28.0.0, 0.30.0, 5.0.0, 0.31.0, 5.1.0, 0.28.0, 1.22.0, 0.32.0, 0.33.0, 0.34.0, 0.35.0, 5.2.0, and 5.3.0.

Use this patch

1. Identify whether the task targets Engine runtime, networking, images, the Engine API, Go integration, Buildx, BuildKit/Dockerfile, or Compose.
2. Read the matching reference before changing configuration, client calls, parsers, or automation.
3. Check both the daemon version and negotiated API version; several defaults and response shapes are API-gated.
4. Treat fresh installations, upgrades, and downgrades separately. Engine 28 and 29 include stateful storage and firewall transitions.
5. Make output parsing explicit. Several human-oriented CLI defaults changed, while event and Compose JSON streams use record framing.

Reference index

| Reference | Topics | | --- | --- | | runtime.md | Daemon startup and reload, storage, mounts, resources, security, rootless, Windows, Swarm, platform support | | networking.md | Attachments, DNS, IPv4/IPv6, IPAM, gateway modes, firewall backends, routing | | images-registry.md | Image store, archives, platform selection, manifests, formats, registry behavior, provenance | | engine-api.md | API compatibility, schema changes, event framing, inspection, updates, deprecations | | go-sdk-cli.md | Go modules and client migrations, removed APIs, CLI behavior and embedding | | buildx.md | Bake, exporters, Imagetools, source policies, builders, provenance, resources | | buildkit-dockerfile.md | BuildKit sources and verification, provenance, deployment, Dockerfile frontend and linting | | compose.md | Compose 5 migration, builds, lifecycle, providers, publish, watch, output, init containers |

Breaking changes and migration priorities

Engine 29 fresh installations

• Fresh Engine 29 installations use the containerd image store by default; upgrades keep their existing store. userns-remap temporarily prevents use of the containerd store.
• Bundled containerd 2.1.5 follows systemd's LimitNOFILE, changing the container default from 1048576 to 1024. Set --ulimit or default-ulimits for workloads that require more descriptors.

{
  "default-ulimits": {
    "nofile": { "Name": "nofile", "Soft": 1048576, "Hard": 1048576 }
  }
}

• Do not assume the old image-list table: docker image ls now uses a collapsed tree and hides untagged images unless --all is set. Give scripts an explicit --format.
• Legacy-link environment variables are no longer injected by default. DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS=1 is only a temporary compatibility switch.

Firewall and network transitions

• Engine 28.0.0 requires kernel ipset support and installs redesigned iptables/ip6tables rules. Before downgrading, remove those rules; rebooting is the simplest documented cleanup.
• Engine 28.0.0 blocks remote direct routing to unpublished ports and prevents neighboring hosts from reaching ports published to host loopback. Publish required ports or deliberately choose a nat-unprotected gateway mode.
• Engine 29 removes the DOCKER-ISOLATION-STAGE-1 and DOCKER-ISOLATION-STAGE-2 chains. Without the userland proxy, cross-network reachability through host-published ports and nat-unprotected networks can increase.
• The nftables backend is experimental. Docker does not enable host forwarding in this mode; configure forwarding and non-Docker interface policy yourself.
• IPv6 ip6tables filtering became stable and default-enabled in 27.0.1. A host that enables IPv6 forwarding independently owns its FORWARD policy.

API compatibility and response parsing

• Engine 25.0.0 API v1.44 removes image VirtualSize; Engine 26.0.0 removes API versions below v1.24 and image Container/ContainerConfig fields.
• Engine 29.0 through 29.2 require daemon API v1.44 or newer; 29.3 lowers the raw daemon floor to v1.40. The v29 CLI and Go client still do not negotiate below v1.44.
• API v1.52 removes many top-level container network fields, omits unset image fields, and can omit GraphDriver with the containerd backend. Read per-network data from NetworkSettings.Networks and tolerate absent optional fields.
• API v1.53 removes the legacy /system/df arrays in favor of usage summaries and deprecates /grpc and /session.
• API v1.55 adds image attestations and makes per-device block-I/O update fields live. Distinguish omitted or null update fields from empty arrays, which clear rules.
• Negotiate event framing explicitly: NDJSON is declared in v1.52, RFC 7464 application/json-seq is accepted in v1.52, and application/jsonl is accepted in v1.53.

Image and registry removals

• Engine 28.2 cannot pull or push Docker Image v1 or manifest v2 schema 1. Republish content as OCI or manifest v2 schema 2.
• Engine 28.2 also removes pull-by-tag fallback after digest resolution. Registries must conform to the OCI Distribution Specification.
• Engine 27 and later reject a non-local remote TCP listener configured with explicit --tls=false or --tlsverify=false. Use verified TLS, a Unix socket, or SSH.
• Engine 29 removes Docker Content Trust commands and classic-builder DCT support from the CLI; install the trust command separately as a CLI plugin when needed.

Go SDK and CLI integration

• Stop importing github.com/docker/docker. Use github.com/moby/moby/client and github.com/moby/moby/api; the parent github.com/moby/moby module is internal, release tags use docker-v29.0.0 form, and the SDK requires Go 1.24 or newer.
• Replace removed NewClient and NewEnvClient; replace ImageCreate with ImagePull or ImageImport.
• Expect option structs and dedicated result structs instead of positional parameters and raw returns. ContainerExec... methods become Exec..., while pull/push results expose JSONMessages iterators.
• Migrate IP/subnet values to netip.Addr and netip.Prefix, MAC values to byte slices compatible with net.HardwareAddr, and container Port to PortSummary.
• Docker CLI embedding lost most exported stock-command constructors and many formatter and Run... helpers. Build on the supported client modules or provide a separate command layer.

Compose 5 migration

• Compose intentionally jumps from v2 to v5; v3 and v4 were skipped to avoid confusion with obsolete Compose file format labels.
• Compose 5 removes its internal BuildKit builder and delegates builds to Bake. Remove dependencies on the former internal builder path.
• Compose 5.2.0 introduces a new state-reconciliation algorithm. Regression-test upgrade convergence for existing projects.
• docker compose ps --format json emits JSON Lines, not one JSON array. Consume each line as a separate JSON value.
• Compose 5.3.0 supports native pre-start init containers.

High-use Engine features

Mount image content

Use type=image (since 28.0.0) and optionally select an internal path with image-subpath:

docker run --mount type=image,source=alpine:latest,target=/mnt,image-subpath=etc alpine:latest

Use bind-create-src when a missing bind source should be created. Replace removed bind-nonrecursive with bind-recursive=disabled:

docker run --mount type=bind,src=/host/data,dst=/data,bind-recursive=disabled IMAGE

Anonymous volumes may now be read-only without naming a source.

Select image platforms

• With the containerd image store, docker image push --platform selects one manifest (since 27.0.1).
• docker load, docker save, and docker history gained one-platform selection in 28.0.0.
• Engine 29 accepts comma-separated platform lists for load and save; the API accepts repeated platform parameters.

docker image save --platform linux/amd64,linux/arm64 -o app.tar app:tag

Control network gateways and address families

Choose the default gateway with extended --network syntax and gw-priority:

docker run --network=name=frontend --network=name=egress,gw-priority=100 IMAGE

Use gateway_mode_ipv4 or gateway_mode_ipv6 values nat, routed, nat-unprotected, or, for an internal network, isolated. Create IPv6-only networks with --ipv6 --ipv4=false where supported.

docker network create --ipv6 --ipv4=false v6-only

Configure per-endpoint interface sysctls with the IFNAME placeholder; API v1.48 no longer migrates container-wide eth0 sysctls automatically.

High-use build features

Enforce source policy

• Buildx 0.31.0 introduces Rego source policy for local contexts; 0.32.0 extends it to Git and HTTP sources and adds Sigstore/provenance inputs.
• Buildx 0.33.0 adds PGP verification and makes the DAP debugger generally available.
• Buildx 0.34.0 adds opt-in BUILDX_DEFAULT_POLICY verification for Docker pipeline images and global bake --policy options.
• Buildx 0.35.0 can proxy build-step network traffic into policy evaluation with BuildKit 0.31.0 or later.

docker buildx build --policy ./policy.rego .
docker buildx bake --policy ./policy.rego

Make outputs and resources deterministic

• Use local exporter mode=delete to replace rather than merge the destination. Outside the working directory, allow buildx.local.delete explicitly.
• Use buildx build --resource or Bake's resource key for CPU and memory limits; this requires BuildKit 0.31.0 or later and Dockerfile v1.25.0 or later.
• Use imagetools create --metadata-file to capture the created descriptor and digest.
• Use Buildx command --timeout where offered to bound waits for remote builders.

High-use Compose features

• Use build.no_cache_filter to bypass cache only for named build stages.
• Use docker compose start --wait to wait for services after starting them.
• Expect lifecycle hooks on restart, post_start hooks for compose run, and provider stop hooks during shutdown.
• Compose recreates a container when an image-mounted digest changes.
• OCI and Git remote resources are supported, including overrides for OCI projects and corrected Windows/SSH path handling.
• docker compose publish honors optional missing environment files and checks literal inline environment values for sensitive data.
• Compose Watch no longer rebuilds depends_on services solely because of that relationship.

Preflight checklist

• Run dockerd --validate --config-file ... to validate configuration and host requirements.
• Verify the active image store and firewall backend with docker info.
• Pin or inspect the Engine API version before relying on fields or omission behavior.
• Make CLI and stream output formats explicit in automation.
• Test firewall reachability after Engine 28/29 upgrades and before any downgrade.
• Test Compose convergence after moving to 5.2.0 or later.
• Read the complete topic reference before changing SDK integrations or compatibility paths.