Clarify what the /images/{name}/tag endpoint does by explaining that
it creates an additional reference (tag) to the source image, and that
existing tags will be overwritten.
The previous description "Tag an image so that it becomes part of a
repository" was unclear about what the operation actually does.
Fixes#22402
Signed-off-by: majiayu000 <1835304752@qq.com>
Document that when a health check command exceeds its configured
timeout, the process is forcibly terminated. This clarifies the
behavior for users who need predictable handling of hung health
check commands.
Fixes#45927
Signed-off-by: majiayu000 <1835304752@qq.com>
The API documentation incorrectly stated that the Data field for
secrets and configs should use Base64-url-safe-encoded format
(RFC 4648 section 5). However, Docker actually uses standard base64
encoding (RFC 4648 section 4).
This caused confusion when users tried to use URL-safe base64 encoding
and received "illegal base64 data" errors.
Update the documentation to correctly reference RFC 4648 section 4
(standard base64) instead of section 5 (URL-safe base64).
Fixes#37671
Signed-off-by: majiayu000 <1835304752@qq.com>
Update the memory stats documentation to clarify differences between
cgroups v1 and v2:
- Add cgroups v2 formula for calculating used_memory using inactive_file
instead of cache field which is not available in v2
- Update memory_stats.stats description to explain that field names
differ between v1 (cache, rss, mapped_file) and v2 (file, anon, inactive_file)
Fixes#43810
Signed-off-by: majiayu000 <1835304752@qq.com>
The API documentation had incorrect descriptions for these fields:
- `/version` endpoint's `Arch` field was described generically but actually
returns the Go runtime's GOARCH value
- `/info` endpoint's `Architecture` field incorrectly stated it returns
GOARCH, but it actually returns the OS-reported hardware architecture
(equivalent to `uname -m`)
This commit corrects the descriptions to accurately reflect the
implementation.
Fixes#49594
Signed-off-by: majiayu000 <1835304752@qq.com>
The /grpc and /session endpoints are now deprecated as the Engine has
been upgraded to properly support HTTP/2 and h2c requests, making these
specialized endpoints unnecessary.
These endpoints will be removed in the next major API version to
complete the cleanup.
Signed-off-by: Paweł Gronowski <pawel.gronowski@docker.com>
I recently had a great time to find out why the tmpfs mode provided did not work
until I found out that the API does not expect octal values but decimal ones.
Therefore, this PR will hopefully clarify the logic and prevent user questions in the future
Signed-off-by: Kai Harder <kai.harder@sap.com>
This change adds type specific fields to `GET /system/df` endpoint with high level information of disk usage. This change also introduces `verbose` query to the endpoint so that detailed information is by default excluded unless queried to reduce memory consumption. The previous top level `DiskUsage` fields (`Images`, `Containers`, `Volumes` and `BuildCache`) are now deprecated and kept for backwards compatibility.
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Austin Vazquez <austin.vazquez@docker.com>
Make invalid states unrepresentable by moving away from stringly-typed
MAC address values in API structs. As go.dev/issue/29678 has not yet
been implemented, provide our own HardwareAddr byte-slice type which
implements TextMarshaler and TextUnmarshaler to retain compatibility
with the API wire format.
When stdlib's net.HardwareAddr type implements TextMarshaler and
TextUnmarshaler and GODEBUG=netmarshal becomes the default, we should be
able to make the type a straight alias for stdlib net.HardwareAddr as a
non-breaking change.
Signed-off-by: Cory Snider <csnider@mirantis.com>
Adds a per-stats OSType field to allow handle the platform-specific fields.
Before this change, the client had to get the OSType field from the server's
API response header and copy it to each record.
Older daemon versions don't have this field, so the client still needs to
handle fallbacks.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Follow-up to f8d3c4e4a7,
this change removes the `Parent` and `DockerVersion` fields from the swagger documentation.
Signed-off-by: Austin Vazquez <austin.vazquez@docker.com>
The BuildCache.Parent field was removed in API v1.42 in [moby@e0db820].
While we had to keep the Go struct field around to backfil the field for
older API versions, it's no longer part of API v1.42 and up (using the
"omitempty" is just an implementation detail).
This patch corrects the swagger files to match this.
[moby@e0db820]: e0db8207f3
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The image inspect response has various fields that were deprecated as
part of the legacy builder, or Dockerfile syntax;
- The `Parent` field is only used for the legacy builder, and only set for
images that are built locally (i.e., not persisted when pulling an image).
- The `DockerVersion` field is only set when building images with the legacy
builder, and empty in most cases.
This patch deprecates the fields in the `InspectResponse` go struct, as
these fields will no longer be set in future once the legacy builder is
removed (`Parent`, `DockerVersion`). The legacy builder's deprecation in
[cli@4d8e457] / [cli@fd22746] (docker 23.0, API v1.42), however the related
API fields were kept so that information of legacy images would not be
discarded.
The API continues to return these fields if set, allowing the client to
print the fields for informational purposes when printing the raw response,
but these fields should be considered "transitional", and not be depended
on; deprecating the fields helps raise awareness.
[cli@4d8e457]: 4d8e45782b
[cli@fd22746]: fd2274692f
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The image inspect response has various fields that are either optional,
or only used if the image was built using the deprecated legacy builder.
This patch marks them as "omitempty" to omit them from the response if
not set:
- The `Parent` field is only used for the legacy builder, and only set for
images that are built locally (i.e., not persisted when pulling an image).
- The `Comment` field is optional, and may not be set, depending on how the
image is produced.
- The `DockerVersion` field is only set when building images with the legacy
builder, and empty in most cases.
- The `Author` field can be set through the `MAINTAINER` instruction in
Dockerfiles, and through the `--author` option on `docker commit`, but
is optional, and won't be set in most situations.
With this patch:
On API v1.52
DOCKER_API_VERSION=v1.52 docker inspect busybox
[
{
"Id": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
"RepoTags": ["busybox:latest"],
"RepoDigests": ["busybox@sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e"],
"Created": "2024-09-26T21:31:42Z",
"Config": {
"Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
"Cmd": ["sh"]
},
"Architecture": "arm64",
"Variant": "v8",
"Os": "linux",
"Size": 1913388,
"RootFS": {
"Type": "layers",
"Layers": ["sha256:6aba5e0d32d91e3e923854dcb30588dc4112bfa1dae82b89535ad31d322a7b19"]
},
"Metadata": {
"LastTagTime": "2025-10-03T22:24:18.440035424Z"
},
"Descriptor": {
"mediaType": "application/vnd.oci.image.index.v1+json",
"digest": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
"size": 9535
}
}
]
On API v1.51 or lower:
DOCKER_API_VERSION=v1.51 docker inspect busybox
[
{
"Architecture": "arm64",
"Author": "",
"Cmd": null,
"Comment": "",
"Config": {
"Cmd": ["sh"],
"Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
},
"Created": "2024-09-26T21:31:42Z",
"Descriptor": {
"digest": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
"mediaType": "application/vnd.oci.image.index.v1+json",
"size": 9535
},
"DockerVersion": "",
"Entrypoint": null,
"Env": null,
"Id": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
"Labels": null,
"Metadata": {
"LastTagTime": "2025-10-03T22:24:18.440035424Z"
},
"OnBuild": null,
"Os": "linux",
"Parent": "",
"RepoDigests": ["busybox@sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e"],
"RepoTags": ["busybox:latest"],
"RootFS": {
"Layers": ["sha256:6aba5e0d32d91e3e923854dcb30588dc4112bfa1dae82b89535ad31d322a7b19"],
"Type": "layers"
},
"Size": 1913388,
"User": "",
"Variant": "v8",
"Volumes": null,
"WorkingDir": ""
}
]
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The `VirtualSize` field was deprecated in [moby@1261fe6], and omitted / removed
in API v1.44 in [moby@913b0f5]. We should not document the field as part of
those API versions as it no longer exists for those.
[moby@1261fe6]: 1261fe69a3
[moby@913b0f5]: 913b0f51ca
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Starting with kernel v6.12, kernel memory TCP accounting is deprecated for cgroups v1.
Note: kernel memory TCP accounting is not supported by cgroups v2.
See d046ff46ee
Signed-off-by: Austin Vazquez <austin.vazquez@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This field was no longer used since Docker 1.11 (API version 1.23)
through [moby@aee260d] and [engine-api@9a9e468] but kept, and deprecated
in [engine-api@167efc7] with a fix-up in [moby@6cfff7e8803a7].
This patch removes the field so that we don't have to carry it in the
new moby/api module.
[moby@aee260d]: aee260d4eb
[engine-api@9a9e468]: 9a9e468f50
[engine-api@167efc7]: 167efc72bb
[moby@6cfff7e8803a7]: 6cfff7e880
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This change defines the generic `Storage` type for use in container inspect responses when using containerd snapshotter backend.
Signed-off-by: Austin Vazquez <austin.vazquez@docker.com>
The `BridgeNfIptables` and `BridgeNfIp6tables` were removed in API v1.50
in commit 6505d3877c, and only returned in
lower API versions.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Except Bridge, all fields of NetworkSettingsBase were deprecated in
v1.44, and are actually never set at all.
The Bridge field was deprecated in v1.51 but it's only set when the
container is connected to the default bridge, and when the daemon is
started with the --bridge option set.
So, remove all those fields and do not backfill them for older API
versions.
Signed-off-by: Albin Kerouanton <albinker@gmail.com>
