From 1f1b70dfdfe03ce989f7c9be9a66ae3b2f29b762 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 18 Jun 2024 16:18:07 +0200 Subject: [PATCH 1/2] docs: add deprecation warning to experimental grapdriver plugins Signed-off-by: Sebastiaan van Stijn --- docs/extend/plugins_graphdriver.md | 9 +++++++++ experimental/README.md | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/extend/plugins_graphdriver.md b/docs/extend/plugins_graphdriver.md index f6558d7f1e35..fbb54bd664f9 100644 --- a/docs/extend/plugins_graphdriver.md +++ b/docs/extend/plugins_graphdriver.md @@ -15,6 +15,15 @@ advisory: experimental # Graphdriver plugins +> **Deprecated** +> +> Support for graphdriver plugins is an experimental feature, which has been +> deprecated. Upcoming releases of the Docker Engine will no longer support +> graphdriver plugins, and users of this feature are recommended to instead +> use the containerd image store, and a custom [snapshotter](https://github.com/containerd/containerd/tree/v1.7.18/docs/snapshotters) +{ .important } + + ## Changelog ### 1.13.0 diff --git a/experimental/README.md b/experimental/README.md index 94fd2c0e01f8..093b805fc842 100644 --- a/experimental/README.md +++ b/experimental/README.md @@ -36,6 +36,6 @@ Option to squash image layers to the base image after successful builds. Checkpoint and restore support for Containers. Metrics (Prometheus) output for basic container, image, and daemon operations. - * [External graphdriver plugins](../docs/extend/plugins_graphdriver.md) + * [External graphdriver plugins](../docs/extend/plugins_graphdriver.md) (Deprecated) * [Checkpoint & Restore](../docs/reference/commandline/checkpoint.md) * [Docker build with --squash argument](../docs/reference/commandline/build.md#squash-an-images-layers---squash-experimental) From 0bc092496fc63e3b58e5a73f23384a5ef60a4d0f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 18 Jun 2024 16:41:55 +0200 Subject: [PATCH 2/2] deprecate experimental graphdriver plugins [Graphdriver plugins] are an experimental feature that allow extending the Docker Engine with custom storage drivers for storing images and containers. This feature was not maintained since its inception, and will no longer be supported in upcoming releases. Users of this feature are recommended to instead configure the Docker Engine to use the [containerd image store], and a custom [snapshotter]. [Graphdriver plugins]: https://github.com/docker/cli/blob/v26.1.4/docs/extend/plugins_graphdriver.md [containerd image store]: https://github.com/docker/docs/blob/31a16f1da2f4a4c94b5a82713aa012f052fb7e6d/content/storage/containerd.md [snapshotter]: https://github.com/containerd/containerd/tree/v1.7.18/docs/snapshotters Signed-off-by: Sebastiaan van Stijn --- docs/deprecated.md | 16 ++ docs/extend/index.md | 2 + docs/extend/plugins_graphdriver.md | 410 ----------------------------- experimental/README.md | 1 - 4 files changed, 18 insertions(+), 411 deletions(-) delete mode 100644 docs/extend/plugins_graphdriver.md diff --git a/docs/deprecated.md b/docs/deprecated.md index e0b6bf608b4b..64567be4be60 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -52,6 +52,7 @@ The table below provides an overview of the current status of deprecated feature |------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------| | Deprecated | [Non-standard fields in image inspect](#non-standard-fields-in-image-inspect) | v27.0 | v28.0 | | Deprecated | [API CORS headers](#api-cors-headers) | v27.0 | v28.0 | +| Deprecated | [Graphdriver plugins (experimental)](#graphdriver-plugins-experimental) | v27.0 | v28.0 | | Deprecated | [Unauthenticated TCP connections](#unauthenticated-tcp-connections) | v26.0 | v28.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 | @@ -148,6 +149,21 @@ part of the underlying image's Config, and deprecated: [Docker image spec]: https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32 [OCI Image Spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/config.go#L24-L62 +### Graphdriver plugins (experimental) + +**Deprecated in Release: v27.0** +**Target For Removal In Release: v28.0** + +[Graphdriver plugins](https://github.com/docker/cli/blob/v26.1.4/docs/extend/plugins_graphdriver.md) +are an experimental feature that allow extending the Docker Engine with custom +storage drivers for storing images and containers. This feature was not +maintained since its inception, and will no longer be supported in upcoming +releases. + +Users of this feature are recommended to instead configure the Docker Engine +to use the [containerd image store](https://docs.docker.com/storage/containerd/), +and a custom [snapshotter](https://github.com/containerd/containerd/tree/v1.7.18/docs/snapshotters) + ### API CORS headers **Deprecated in Release: v27.0** diff --git a/docs/extend/index.md b/docs/extend/index.md index 22ab0f3f3066..c90a42cb4f7e 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -2,6 +2,8 @@ title: Docker Engine managed plugin system description: Develop and use a plugin with the managed plugin system keywords: "API, Usage, plugins, documentation, developer" +aliases: + - "/engine/extend/plugins_graphdriver/" --- - [Installing and using a plugin](index.md#installing-and-using-a-plugin) diff --git a/docs/extend/plugins_graphdriver.md b/docs/extend/plugins_graphdriver.md deleted file mode 100644 index fbb54bd664f9..000000000000 --- a/docs/extend/plugins_graphdriver.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -description: "How to manage image and container filesystems with external plugins" -keywords: "Examples, Usage, storage, image, docker, data, graph, plugin, api" -advisory: experimental ---- - - - -# Graphdriver plugins - -> **Deprecated** -> -> Support for graphdriver plugins is an experimental feature, which has been -> deprecated. Upcoming releases of the Docker Engine will no longer support -> graphdriver plugins, and users of this feature are recommended to instead -> use the containerd image store, and a custom [snapshotter](https://github.com/containerd/containerd/tree/v1.7.18/docs/snapshotters) -{ .important } - - -## Changelog - -### 1.13.0 - -- Support v2 plugins - -# Docker graph driver plugins - -Docker graph driver plugins enable admins to use an external/out-of-process -graph driver for use with Docker engine. This is an alternative to using the -built-in storage drivers, such as overlay2. - -You need to install and enable the plugin and then restart the Docker daemon -before using the plugin. See the following example for the correct ordering -of steps. - -```console -$ docker plugin install cpuguy83/docker-overlay2-graphdriver-plugin # this command also enables the driver - -$ pkill dockerd -$ dockerd --experimental -s cpuguy83/docker-overlay2-graphdriver-plugin -``` - -# Write a graph driver plugin - -See the [plugin documentation](https://docs.docker.com/engine/extend/) for detailed information -on the underlying plugin protocol. - - -## Graph Driver plugin protocol - -If a plugin registers itself as a `GraphDriver` when activated, then it is -expected to provide the rootfs for containers as well as image layer storage. - -### /GraphDriver.Init - -**Request**: -```json -{ - "Home": "/graph/home/path", - "Opts": [], - "UIDMaps": [], - "GIDMaps": [] -} -``` - -Initialize the graph driver plugin with a home directory and array of options. -These are passed through from the user, but the plugin is not required to parse -or honor them. - -The request also includes a list of UID and GID mappings, structed as follows: -```json -{ - "ContainerID": 0, - "HostID": 0, - "Size": 0 -} -``` - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a non-empty string error if an error occurred. - - -### /GraphDriver.Capabilities - -**Request**: -```json -{} -``` - -Get behavioral characteristics of the graph driver. If a plugin does not handle -this request, the engine will use default values for all capabilities. - -**Response**: -```json -{ - "ReproducesExactDiffs": false, -} -``` - -Respond with values of capabilities: - -* **ReproducesExactDiffs** Defaults to false. Flags that this driver is capable -of reproducing exactly equivalent diffs for read-only filesystem layers. - - -### /GraphDriver.Create - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "Parent": "2cd9c322cb78a55e8212aa3ea8425a4180236d7106938ec921d0935a4b8ca142", - "MountLabel": "", - "StorageOpt": {} -} -``` - -Create a new, empty, read-only filesystem layer with the specified -`ID`, `Parent` and `MountLabel`. If `Parent` is an empty string, there is no -parent layer. `StorageOpt` is map of strings which indicate storage options. - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.CreateReadWrite - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "Parent": "2cd9c322cb78a55e8212aa3ea8425a4180236d7106938ec921d0935a4b8ca142", - "MountLabel": "", - "StorageOpt": {} -} -``` - -Similar to `/GraphDriver.Create` but creates a read-write filesystem layer. - -### /GraphDriver.Remove - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187" -} -``` - -Remove the filesystem layer with this given `ID`. - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.Get - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "MountLabel": "" -} -``` - -Get the mountpoint for the layered filesystem referred to by the given `ID`. - -**Response**: -```json -{ - "Dir": "/var/mygraph/46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "Err": "" -} -``` - -Respond with the absolute path to the mounted layered filesystem. -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.Put - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187" -} -``` - -Release the system resources for the specified `ID`, such as unmounting the -filesystem layer. - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.Exists - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187" -} -``` - -Determine if a filesystem layer with the specified `ID` exists. - -**Response**: -```json -{ - "Exists": true -} -``` - -Respond with a boolean for whether or not the filesystem layer with the specified -`ID` exists. - -### /GraphDriver.Status - -**Request**: -```json -{} -``` - -Get low-level diagnostic information about the graph driver. - -**Response**: -```json -{ - "Status": [[]] -} -``` - -Respond with a 2-D array with key/value pairs for the underlying status -information. - - -### /GraphDriver.GetMetadata - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187" -} -``` - -Get low-level diagnostic information about the layered filesystem with the -with the specified `ID` - -**Response**: -```json -{ - "Metadata": {}, - "Err": "" -} -``` - -Respond with a set of key/value pairs containing the low-level diagnostic -information about the layered filesystem. -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.Cleanup - -**Request**: -```json -{} -``` - -Perform necessary tasks to release resources help by the plugin, such as -unmounting all the layered file systems. - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a non-empty string error if an error occurred. - - -### /GraphDriver.Diff - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "Parent": "2cd9c322cb78a55e8212aa3ea8425a4180236d7106938ec921d0935a4b8ca142" -} -``` - -Get an archive of the changes between the filesystem layers specified by the `ID` -and `Parent`. `Parent` may be an empty string, in which case there is no parent. - -**Response**: - -``` -{{ TAR STREAM }} -``` - -### /GraphDriver.Changes - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "Parent": "2cd9c322cb78a55e8212aa3ea8425a4180236d7106938ec921d0935a4b8ca142" -} -``` - -Get a list of changes between the filesystem layers specified by the `ID` and -`Parent`. If `Parent` is an empty string, there is no parent. - -**Response**: -```json -{ - "Changes": [{}], - "Err": "" -} -``` - -Respond with a list of changes. The structure of a change is: -```json - "Path": "/some/path", - "Kind": 0, -``` - -Where the `Path` is the filesystem path within the layered filesystem that is -changed and `Kind` is an integer specifying the type of change that occurred: - -- 0 - Modified -- 1 - Added -- 2 - Deleted - -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.ApplyDiff - -**Request**: - -``` -{{ TAR STREAM }} -``` - -Extract the changeset from the given diff into the layer with the specified `ID` -and `Parent` - -**Query Parameters**: - -- id (required)- the `ID` of the new filesystem layer to extract the diff to -- parent (required)- the `Parent` of the given `ID` - -**Response**: -```json -{ - "Size": 512366, - "Err": "" -} -``` - -Respond with the size of the new layer in bytes. -Respond with a non-empty string error if an error occurred. - -### /GraphDriver.DiffSize - -**Request**: -```json -{ - "ID": "46fe8644f2572fd1e505364f7581e0c9dbc7f14640bd1fb6ce97714fb6fc5187", - "Parent": "2cd9c322cb78a55e8212aa3ea8425a4180236d7106938ec921d0935a4b8ca142" -} -``` - -Calculate the changes between the specified `ID` - -**Response**: -```json -{ - "Size": 512366, - "Err": "" -} -``` - -Respond with the size changes between the specified `ID` and `Parent` -Respond with a non-empty string error if an error occurred. diff --git a/experimental/README.md b/experimental/README.md index 093b805fc842..f85ed3e3889a 100644 --- a/experimental/README.md +++ b/experimental/README.md @@ -36,6 +36,5 @@ Option to squash image layers to the base image after successful builds. Checkpoint and restore support for Containers. Metrics (Prometheus) output for basic container, image, and daemon operations. - * [External graphdriver plugins](../docs/extend/plugins_graphdriver.md) (Deprecated) * [Checkpoint & Restore](../docs/reference/commandline/checkpoint.md) * [Docker build with --squash argument](../docs/reference/commandline/build.md#squash-an-images-layers---squash-experimental)