Changes for version 0.004 - 2026-08-30
- The typed object model: `list` and `inspect` on every resource now return generated `API::Docker::Type::*` objects with snake_case accessors (`$c->id`, `$c->size_root_fs`) instead of hashrefs. An unrecognised field is kept and re-sent unchanged rather than dropped, and `since` is documentation only.
- The hand-written entity classes are gone. Their convenience methods (`start`, `stop`, `logs`, ...) keep their signatures and move to `API::Docker::Role::Entity::*`, composed onto the generated classes; the old names (`API::Docker::Container`, `::Image`, `::Network`, `::Volume`, `::Plugin`, `::Secret`, `::Config`) ship as stubs that croak, naming what replaces them.
- New streaming options `on_event`, `on_frame` and `on_chunk` on the HTTP verbs, wired into `system->events`, `containers->logs`/`stats`/`attach`, `exec->start`, the `images` build/pull/push/load/get family and the `plugins` install/upgrade/push. A callback receives each event, frame or chunk as it arrives; `$stop->()` ends the stream early. Without one the unbounded endpoints still block.
- New `read_timeout` and `connect_timeout`, as client attributes and per-request options, off by default. `read_timeout` is idle time since the last byte; both croak `API::Docker::Error::Timeout`, which carries whatever already arrived. A new `TIMEOUTS` section in `API::Docker` documents what each bounds. `containers->stats` is deliberately not bounded by `read_timeout` -- its stream keeps producing rather than going idle.
- New `API::Docker::Role::Using`: `$docker->containers->using(read_timeout => 5)->list` clones a resource class to bound a run of calls. Every request the run makes, version negotiation included, carries the bound; an explicit `0` turns a client-wide default off.
- A truncated response is now an exception. A body shorter than its Content-Length, a short or malformed chunk, a missing zero chunk, a malformed status line, a bad `Content-Length` or a stray 1xx all croak `API::Docker::Error::Truncated` instead of being handed back as a whole response.
- A status of 400 or above croaks `API::Docker::Error::HTTP` instead of a plain string, carrying `status`, `reason`, `body` and decoded `data`. It stringifies exactly as the old string croak did, so text-matching callers are unaffected.
- `tls => 1` now speaks real TLS over `tcp://`. `cert_path` names the `docker` CLI's `ca.pem`/`cert.pem`/`key.pem` layout, `tls_insecure` turns verification off, and `tls` defaults from `$ENV{DOCKER_TLS_VERIFY}`. `IO::Socket::SSL` is a recommended dependency, loaded on the first TLS connection.
- New `response => \%h` option fills `status`, `reason` and `headers`, including for a request that croaked. New `head` verb beside `get`/`post`/`put`/`delete_request`, which never waits for a body.
- `negotiate_version` croaks, naming `GET /version` and the expected shape, when the body is not a JSON object carrying an `ApiVersion` of the form `N.N`.
- New `API::Docker::Role::Filters`, consumed by all eight resource classes and applied at every `filters` call site: a bare value, a boolean or a mis-shaped filter is normalised to the engine's JSON map-of-arrays instead of silently matching nothing.
- JSON request bodies send booleans as real `true`/`false`; a caller may pass `1`/`0` or a JSON boolean interchangeably.
- `_uri_encode` UTF-8-encodes a decoded character string before percent-escaping, so a name or tag typed as characters (`ü`, `中`) goes out as valid UTF-8.
- A request path outside the RFC 3986 origin-form character set is refused before it reaches the daemon, closing a request-line injection through a container name or image reference.
- An ArrayRef query parameter expands into one repeated `k=v` pair per element (`names=a&names=b`), which some endpoints require.
- A bare JSON scalar body (`null`, `true`, a number, a quoted string) is decoded rather than handed back as raw bytes; `raw` and `ndjson` return `''` and `[]` for a zero-byte body instead of `undef`.
- Registry credentials reach `images->pull` (`auth`, sent as `X-Registry-Auth`) and `images->build` (`registry_config`, sent as `X-Registry-Config`), sent only when given. An already-base64 auth value in the standard alphabet is respelled URL-safe, which the engine requires.
- `images->pull` no longer appends a default `tag` onto a reference that already carries a `:tag` or `@digest`.
- New `images->get`, `->get_all` and `->load`: the image tar roundtrip in and out of a daemon without a registry. New `images->commit` (POST /commit) and `images->build_prune` (POST /build/prune, the BuildKit cache, a different store from the dangling images `images->prune` deletes).
- New container endpoints: `get_archive`, `put_archive`, `stat_archive` (the `docker cp` primitives), `changes`, `export`, `resize` and the one-way half of `attach`. `attach` defaults to `stream => 0, logs => 1` (replay and return) and refuses a container that is not running unless `require_running => 0`.
- `containers->start`/`stop`/`restart`/`pause`/`unpause` return 1 when the call changed the container's state and 0 when it was already in it (the engine answers a no-op with 304), instead of always undef.
- `containers->stats` croaks `API::Docker::Error::HTTP` when Podman reports a failure inside a 200 response, instead of handing the error object back as a reading.
- New `API::Docker::API::Plugins` (`$docker->plugins`): `list`, `privileges`, `install`, `inspect`, `remove`, `enable`, `disable`, `upgrade`, `push` and `configure`. Needs a real Docker daemon; Podman serves no `/plugins`.
- New `API::Docker::API::Secrets` and `API::Docker::API::Configs`: `list`, `create`, `inspect`, `update` and `remove`. `Data` is base64-encoded for the caller; `update` takes the current `Version.Index` as a mandatory concurrency token.
- New `API::Docker::API::System::auth` (POST /auth): check registry credentials without pulling or pushing. A rejected credential croaks.
- New `API::Docker::API::Distribution` (`inspect`/`exists`, GET /distribution/{name}/json): ask a registry for a manifest without pulling. `exists` answers `1`/`0` and tells a registry's own 404 apart from an engine that serves no such route.
- Declare a minimum Perl of 5.014 (`s///r` in `Role::HTTP`) and add the core modules `Errno`, `IO::Handle`, `Scalar::Util` and `Socket` to `cpanfile`. Stop shipping `spec/` and `maint/` in the built dist.
- Swarm (`/swarm`, `/nodes`, `/services`, `/tasks`) is documented as a permanent scope decision, not a gap: Podman implements none of it and no consumer needs it. `secrets` and `configs` stand on their own and stay covered.
Modules
Perl client for the Docker Engine API
Docker Engine Configs API
Docker Engine Containers API
Docker Engine Distribution API
Docker Engine Exec API
Docker Engine Images API
Docker Engine Networks API
Docker Engine Plugins API
Docker Engine Secrets API
Docker Engine System API
Docker Engine Volumes API
Removed in 0.004 -- replaced by API::Docker::Type::Config
Removed in 0.004 -- replaced by API::Docker::Type::ContainerSummary and ContainerInspectResponse
Error status returned by the Docker Engine on the status line
Failure reported inside a Docker Engine progress stream
Read timeout while waiting for the Docker Engine
The daemon closed before the response it announced was complete
Removed in 0.004 -- replaced by API::Docker::Type::ImageSummary and ImageInspect
Removed in 0.004 -- replaced by API::Docker::Type::Network
Removed in 0.004 -- replaced by API::Docker::Type::Plugin
The client reference an entity delegates through
Config operations, on the generated config type
Container operations, on the generated container types
Image operations, on the generated image types
Network operations, on the generated network type
Plugin operations, on the generated plugin type
Secret operations, on the generated secret type
Volume operations, on the generated volume type
The filters query parameter, normalised into the one shape the engine reads
HTTP transport role for Docker Engine API
coerce known boolean keys of a request body to JSON booleans
AuthConfig encoding shared by the registry-facing endpoints
Instance behaviour of a generated API::Docker::Type class
A resource class clone that bounds a run of calls
Removed in 0.004 -- replaced by API::Docker::Type::Secret
The DSL and attribute registry behind the generated Docker types
An IPv4 or IPv6 IP address
The body of a POST /auth request
Information about a build cache record
One event of the stream a POST /build answers with
Information about the swarm as is returned by the "/info" endpoint
Options and information specific to, and only present on, Swarm CSI cluster volumes
Information about the global status of the volume
One entry of ClusterVolume.PublishStatus
Cluster-specific options used to create the volume
Defines how the volume is used by tasks
Requirements for the accessible topology of the volume
The desired capacity that the volume should be created with
One cluster volume secret entry
Commit holds the Git-commit (SHA1) that a binary was built from, as reported in the version-string of external tools, such as containerd, or runC
One entry of the 200 response to GET /configs
The config-only network source to provide the configuration for this network
The body of a POST /configs/create request
Blkio stats entry
BlkioStats stores all IO service stats for data read and write
CPU related info of the container
All CPU stats aggregated since container inception
Configuration for a container that is portable between hosts
OK response to ContainerCreate operation
The body of the 200 response to GET /containers/{id}/json
Aggregates all memory stats since container inception on Linux
Aggregates the network stats of one container
PidsStats contains Linux-specific stats of a container's process-IDs (PIDs)
Container's running state
Statistics sample for a container
represents the status of a container
StorageStats is the disk I/O stats for read/write on Windows
One entry of the 200 response to GET /containers/json
Summary of host-specific runtime information of the container
Summary of the container's network settings
CPU throttling stats of the container
Container "top" response
Response for a successful container-update
container waiting error, if any
OK response to ContainerWait operation
Information for connecting to the containerd instance that is used by the daemon
The namespaces that the daemon uses for running containers and plugins in containerd
One event of the stream a POST /images/create answers with
A device that can be used by a container
A device mapping between the host and container
A request for devices to be sent to device drivers
Describes the result obtained from contacting the registry to retrieve image metadata
A driver (network, logging, secrets)
Information about the storage driver used to store the container's and image's filesystem
An endpoint's IPAM configuration
One entry of EndpointSpec.Ports
Configuration for a network endpoint
Properties that can be configured to access and load balance a service
EngineDescription provides information about an engine
One entry of EngineDescription.Plugins
The value of BuildInfo.errorDetail
Represents an error
Actor describes something that generates events, like a container, network, or a volume
The information an event contains
Change in the container's filesystem
Information about the daemon's firewalling configuration
User-defined resources can be either Integer resources (e.g, SSD=3) or String resources (e.g, GPU=UUID1)
An integer-valued user-defined resource
A string-valued user-defined resource
Information about the container's healthcheck results
A test to perform to check that the container is healthy
Information about a single run of a healthcheck probe
Container configuration that depends on the host we are running on
The logging configuration for this container
Response to an API call that returns just an Id
The IPAM field of the body of a POST /networks/create request
One entry of IPAM.Config
Configuration of the image
One entry of the 200 response to DELETE /images/{name}
individual image layer information in response to ImageHistory operation
Image ID or Digest
Information about an image in the local image cache
Additional metadata of the image in the local cache
Information about the image's RootFS, including the layer IDs
A summary of an image manifest
The image data for the attestation manifest
The image data for the image manifest
The unpacked size of an image manifest
The sizes of one manifest of an image
One entry of the 200 response to GET /images/json
Information about a registry
The tokens workers and managers need to join the swarm
An object describing a limit on resources which can be requested by a task
The status of a manager
One entry of a container's Mounts specification
Optional configuration for the bind type
Optional configuration for the image type
Optional configuration for the tmpfs type
Optional configuration for the volume type
The volume driver a mount's volume is to be created with
A mount point configuration inside the container
One entry of the 200 response to GET /networks
Specifies how a service should be attached to a particular network
One value of Network.Containers
OK response to NetworkCreate operation
NetworkSettings exposes the network settings in the API
The container's networking configuration for each of its interfaces
One entry of the 200 response to GET /nodes
NodeDescription encapsulates the properties of the Node as reported by the agent
The body of a POST /nodes/{id}/update request
The status of a node
A descriptor struct containing digest, media type, and size, as defined in the OCI Content Descriptors Specification
Describes the platform which the image in the manifest runs on, as defined in the OCI Image Index Specification
The version number of the object such as node, service, etc
One peer of an overlay network
Represents a peer-node in the swarm
The platform (Arch/OS)
A plugin for the Engine API
The config of a plugin
The command-line arguments a plugin accepts
The interface between Docker and the plugin
The Linux-specific capabilities and devices a plugin needs
The network mode a plugin runs in
The root filesystem of a plugin
The user and group a plugin's process runs as
Settings that can be modified by users
One entry of Plugin.Config.Linux.Devices
One entry of Plugin.Config.Env
One entry of Plugin.Config.Interface.Types
One entry of Plugin.Config.Mounts
Describes a permission the user has to accept upon installing the plugin
Available plugins per type
An open port on a container
A binding between a host IP address and a host port
represents the port status of a task's host ports whose service has published host ports
The ProcessConfig field of the 200 response to GET /exec/{id}/json
The value of BuildInfo.progressDetail
One event of the stream a POST /images/{name}/push answers with
Daemon registry services configuration
An object describing the resources which can be advertised by a node and requested by a task
A container's resources (cgroups config, ulimits, etc)
A per-device block IO weight
One resource limit to set in a container
The behavior to apply when the container exits
An OCI compliant runtime
One entry of the 200 response to GET /secrets
The body of a POST /secrets/create request
One entry of the 200 response to GET /services
The resolved endpoint of a service
One entry of Service.Endpoint.VirtualIPs
The status of the service when it is in one of ReplicatedJob or GlobalJob modes
The status of the service's tasks
The status of a service update
contains the information returned to a client on the creation of a new service
User modifiable configuration for a service
Scheduling mode for the service
The replicated mode of a service, and its replica count
The mode used for services with a finite number of tasks that run to a completed state
Specification for the rollback strategy of the service
Specification for the update strategy of the service
The body of the 200 response to POST /services/{id}/update
The body of the 200 response to GET /swarm
Represents generic information about swarm
User modifiable swarm configuration
CA configuration
One entry of SwarmSpec.CAConfig.ExternalCAs
Dispatcher configuration
Parameters related to encryption-at-rest
Orchestration configuration
Raft configuration
Defaults for creating tasks in this cluster
The log driver to use for tasks created in the orchestrator if unspecified by a service
The body of the 200 response to GET /info
One entry of SystemInfo.DefaultAddressPools
Response of Engine API: GET "/version"
One entry of SystemVersion.Components
The name of the platform the daemon reports itself as
Information about the issuer of leaf TLS certificates and the trusted root CA certificate
One entry of the 200 response to GET /tasks
User modifiable task configuration
Container spec for the service
One entry of TaskSpec.ContainerSpec.Configs
A specific target that is backed by a file
Specification for DNS related configurations in resolver configuration file (resolv.conf)
Security options for the container
Options for configuring AppArmor on the container
CredentialSpec for managed service account (Windows only)
SELinux labels of the container
Options for configuring seccomp on the container
One entry of TaskSpec.ContainerSpec.Secrets
A specific target that is backed by a file
One entry of TaskSpec.ContainerSpec.Ulimits
Specifies the log driver to use for tasks created from this spec
Read-only spec type for non-swarm containers attached to swarm overlay networks
Where in the swarm a task may be scheduled
One scheduling preference of a task
The node attribute a task is spread over
Plugin spec for the service
Resource requirements which apply to each individual container created as part of the service
Specification for the restart policy which applies to containers created as part of this service
represents the status of a task
A per-device block IO rate limit
A map of topological domains to topological segments
The body of the 200 response to GET /volumes/{name}
Usage details about the volume
Volume configuration
Volume list response
Removed in 0.004 -- replaced by API::Docker::Type::Volume