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 f6558d7f1e35..000000000000 --- a/docs/extend/plugins_graphdriver.md +++ /dev/null @@ -1,401 +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 - -## 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 94fd2c0e01f8..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) * [Checkpoint & Restore](../docs/reference/commandline/checkpoint.md) * [Docker build with --squash argument](../docs/reference/commandline/build.md#squash-an-images-layers---squash-experimental)