Agent-Skills.md

Agent Skills: Docker Compatibility Guidance

Docker

UncategorizedID: nevaberry/nevaberry-plugins/docker-knowledge-patch

Repository

nevaberry/nevaberry-plugins
NevaberryLicense: MIT
23

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Nevaberry/nevaberry-plugins/tree/HEAD/plugins/knowledge-patch/patches-codex/docker-knowledge-patch

Skill Files

Browse the full folder contents for docker-knowledge-patch.

Download Skill

Loading file tree…

plugins/knowledge-patch/patches-codex/docker-knowledge-patch/SKILL.md

Skill Metadata

Name
docker-knowledge-patch
Description
Docker

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

| Reference | Topics | | --- | --- | | BuildKit and Dockerfile frontend | Dockerfile behavior, LLB sources, provenance, security fixes, cgroups | | Buildx, Bake, imagetools, and builders | Source policies, Bake variables, exporters, builder drivers, attestations | | Docker Compose 5 | Reconciliation, lifecycle hooks, remote resources, Watch, config and publish behavior | | Engine API compatibility and deprecations | API floors, schemas, event streams, inspection, deprecations | | Go SDK and CLI integration | Module paths, call shapes, type moves, removed symbols, CLI plugins | | Images, manifests, archives, and registries | Image stores, platform selection, mounts, metadata, registry behavior | | Networking, DNS, IPAM, and firewalls | Attachments, IPv6, gateway modes, DNS, routing, firewall backends | | Engine runtime, daemon, and platform | Daemon lifecycle, security, logging, container lifecycle, Windows and rootless behavior |

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.