Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs/deprecated: Deprecate Container fields in image inspect #4893

Merged
merged 1 commit into from
Mar 18, 2024
Merged

docs/deprecated: Deprecate Container fields in image inspect #4893

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/deprecated.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ The table below provides an overview of the current status of deprecated feature
| Status | Feature | Deprecated | Remove |
|------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------|
| Deprecated | [Unauthenticated TCP connections](#unauthenticated-tcp-connections) | v26.0 | v27.0 |
| Deprecated | [`Container` and `ContainerConfig` fields in Image inspect](#container-and-containerconfig-fields-in-image-inspect) | v25.0 | v26.0 |
| Deprecated | [Deprecate legacy API versions](#deprecate-legacy-api-versions) | v25.0 | v26.0 |
| Deprecated | [Container short ID in network Aliases field](#container-short-id-in-network-aliases-field) | v25.0 | v26.0 |
| Deprecated | [IsAutomated field, and "is-automated" filter on docker search](#isautomated-field-and-is-automated-filter-on-docker-search) | v25.0 | v26.0 |
Expand Down Expand Up @@ -138,6 +139,19 @@ For further information, assistance, and step-by-step instructions on
configuring TLS (or SSH) for the Docker daemon, refer to
[Protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/).

### `Container` and `ContainerConfig` fields in Image inspect

**Deprecated in Release: v25.0**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did we forget mentioning these as deprecated for the v25 release? Wondering if that means we need to wait for v27.0 to remove them, or did we document it in the API changes at the time?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we forgot to put it there, but we mentioned it in version-history.md 🙈

The Container and ContainerConfig fields in the GET /images/{name}/json response are deprecated and will no longer be included in API v1.45.

But I'm fine with waiting for v27.0 for the removal, especially since the docker-py with the fixed tests is not released yet.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Arf, I somehow missed your last comments. Some thoughts (maybe we don't have to postpone the removal);

  • The API changes document is the "canonical" place for changes in the engine API, including deprecations
  • I thought we always included a mention like "for changes and deprecations in the API refer to <link to API changes>"; if we don't, we should fix that.
  • ☝️ perhaps we should also do a cross-reference in this deprecated page, to do the same ("for an overview of changes in API ...")

That said; I don't think it necessarily hurts to call out / repeat important changes here, but we may not have to for all of them.

@vvoland @dvdksn WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW; for some of these, it would at least make things easier as well, because the API is versioned so if you use the "older API version", nothing changes, but yeah, in some cases that may affect output of docker CLI commands.

docker inspect was meant to show the underlying "low-level" information, which would still be "accurate" here, but that underlying information now may no longer have these fields (or not set).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We link to both the deprecated.md and version-history.md from the release note:

image

I don't think it hurts to also cross-reference between these two.

If version-history.md is canonical then we should be safe to remove in 26.0 since this was called out (and linked from the release note). It just wasn't called out everywhere.

image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the removal notice to v26.

**Target For Removal In Release: v26.0**

The `Container` and `ContainerConfig` fields returned by `docker inspect` are
mostly an implementation detail of the classic (non-BuildKit) image builder.
These fields are not portable and are empty when using the
BuildKit-based builder (enabled by default since v23.0).
These fields are deprecated in v25.0 and will be omitted starting from v26.0.
vvoland marked this conversation as resolved.
Show resolved Hide resolved
If image configuration of an image is needed, you can obtain it from the
`Config` field.

### Deprecate legacy API versions

**Deprecated in Release: v25.0**
Expand Down