Docker Knowledge Patch

Docker Compatibility Guidance

Use this skill when upgrading Docker Engine, integrating with the Engine API or Go client, operating BuildKit or Buildx, or adopting Docker Compose 5 behavior. Start with the quick reference for migration blockers, then load only the topic reference needed for the task.

Reference index

Upgrade blockers and removals

Engine configuration and extensions

• Remove the --oom-score-adjust daemon option and replace the logentries logging driver before moving to Engine 25.0.0.
• Engine 28 removes the daemon API CORS option, external graph-driver plugins, the temporary Windows windows-dns-proxy flag, and Fluentd fluentd-async-connect.
• Engine 28 requires a matching updated docker-proxy; older proxy binaries are incompatible. rootlesskit-docker-proxy is removed from the distribution.
• --allow-nondistributable-artifacts no longer has any effect and emits a deprecation warning.
• Docker Content Trust commands are removed from the Engine 29 CLI and are available only by building a separate plugin.

API and client compatibility

• Engine 26 removes API versions older than v1.24.
• Engine 29.0 through 29.2 requires API v1.44 or later; Engine 29.3 lowers the minimum to v1.40. Clients that target earlier 29.x daemons must still negotiate v1.44 or newer.
• API v1.52 removes legacy top-level network fields from container inspection; read endpoint data from NetworkSettings.Networks.
• API v1.53 removes the legacy disk-usage fields LayersSize, Images, Containers, Volumes, and BuildCache.
• API v1.53 deprecates POST /grpc and POST /session.
• The Go SDK removes deprecated constructors, old image-client interfaces, and numerous packages in Engine 29. Use the supported github.com/moby/moby/client and github.com/moby/moby/api modules; the SDK requires Go 1.24 or later.

CLI and output migrations

• Engine 28 renames docker stop --time and docker restart --time to --timeout.
• Engine 29 changes docker image ls to a collapsed tree-style view, hides untagged images unless --all is used, stops truncating image names, and removes VirtualSize from JSON and formatting output.
• docker compose ps --format json emits JSON Lines rather than one JSON array.
• docker buildx install and docker buildx uninstall are deprecated; invoke docker buildx directly.
• Buildx policy evaluation renames --filename to --file; the old long flag remains deprecated.

Networking quick reference

Firewall behavior

• ip6tables is enabled by default for Linux bridge networks. On IPv6-enabled bridges it restricts external access to published ports and enables outbound masquerading.
• Engine 28 blocks remote direct access to unpublished container ports. Publish required ports or deliberately use nat-unprotected when that exposure is intended.
• Engine 28 changes bridge iptables and ip6tables rules and requires kernel ipset support. Before downgrading, remove the new rules; rebooting is the documented simplest cleanup.
• The experimental Engine 29 nftables backend does not enable host IP forwarding. If a bridge needs forwarding while it is disabled, daemon startup or network creation fails.
• The daemon no longer appends permissive host INPUT rules for encrypted overlays. Restrictive hosts may need an explicit rule for incoming encrypted overlay traffic.

Addressing and routes

• Extended --network syntax supports multiple attachments, per-attachment MAC and link-local addresses, endpoint driver options, gateway priority, and container-side interface names.
• The highest gw-priority selects the default gateway; equal priorities are resolved by network-name order.
• docker network create --ipv4=false disables IPv4 assignment, subject to the driver and platform limits in the networking reference.
• A routed bridge installs no NAT or masquerading for published ports. The surrounding network must route container addresses to the host.
• Macvlan and IPvlan L2 networks in Engine 29 receive no default gateway unless IPAM explicitly supplies --gateway.

Images and registries quick reference

Platform selection and stores

• The containerd image store supports docker image push --platform for one locally stored platform manifest.
• Engine 28 adds single-platform selection to docker load, docker save, and docker history.
• Engine 29 accepts comma-separated platform lists for docker image load and docker image save; the APIs accept repeated platform parameters.
• Fresh Engine 29 installations use the containerd image store by default, but existing installations are not switched automatically and userns-remap installations are excluded.
• Engine 29.7.0 graduates the image mount type from experimental status.

Metadata and compatibility

• Engine 26 image inspection removes Container and ContainerConfig.
• Engine API v1.48 adds image Manifests; containerd-backed responses also add OCI descriptor fields.
• Engine 29.2 adds trusted image Identity data, and 29.3 adds an identity query parameter to GET /images/json.
• API v1.55 adds GET /images/{name}/attestations with platform, predicate-type, and statement-body controls.
• Saved image tar archives are OCI compliant from Engine 25.0.0.

Build quick reference

Provenance and policies

• BuildKit provenance defaults to SLSA v1.0. Set the provenance version attribute when v0.2 output is required.
• Buildx can enforce Rego source policies, evaluate and test them, and apply them to local, remote Git, and HTTP sources.
• Attestation-aware policy builtins can validate signed Sigstore bundles, fetch attestations from the GitHub API, and inspect image provenance. Provenance policy inputs require BuildKit 0.28 or later.
• Default verification of Docker pipeline images is opt-in through BUILDX_DEFAULT_POLICY; Buildx 0.36.0 extends default-policy checks to the BuildKit release image used by a docker-container builder.

Exports and resources

• A local export with mode=delete replaces the destination instead of merging into it. The destination must be below the working directory unless --allow=buildx.local.delete is supplied or the TUI confirms the action.
• Registry-oriented exports initialized with --push or -o type=registry do not unpack images created in the Docker image store.
• Build requests can set CPU and memory limits through --resource or a Bake target resource key when the stated BuildKit and Dockerfile requirements are met.
• imagetools create --metadata-file writes properties such as the created descriptor and digest for automation.

Compose quick reference

Build and reconciliation

• Compose 5 delegates builds to Docker Bake and removes its internal BuildKit builder. Integrations that depended on the internal builder must migrate to the delegated path.
• Compose recreates a container when the digest of an image mounted into it changes.
• The first docker compose up after the image-digest reconciliation upgrade may recreate existing containers once.
• Compose 5.2 introduces a new workload reconciliation algorithm, so existing workloads can behave differently after upgrading even when their files have not changed.
• Compose 5.4 includes volume recreation and network lifecycle in reconciliation plans.

Lifecycle and configuration

• Service hooks run on restart; docker compose run executes the target service's post_start hooks; external providers gain a stop hook.
• Compose supports native init containers that run before the main workload.
• docker compose config --variables extracts variables without first requiring full model validation.
• docker compose config --hash accounts for zero-replica services and, in Compose 5.5, resolves service environments before computing the hash.
• docker compose pull honors pull_policy refresh windows such as daily, weekly, and every_N.

Apply guidance conservatively

Preserve every stated condition when using these references: API negotiation, image-store backend, operating system, network driver, experimental status, and minimum component versions all affect whether an item applies. Do not infer a replacement or outcome where a reference only records a behavior change.