mirror of https://github.com/docker/cli.git
406 lines
8.0 KiB
Markdown
406 lines
8.0 KiB
Markdown
---
|
|
description: "How to manage image and container filesystems with external plugins"
|
|
keywords: "Examples, Usage, storage, image, docker, data, graph, plugin, api"
|
|
advisory: experimental
|
|
---
|
|
|
|
<!-- This file is maintained within the docker/cli GitHub
|
|
repository at https://github.com/docker/cli/. Make all
|
|
pull requests against that repo. If you see this file in
|
|
another repository, consider it read-only there, as it will
|
|
periodically be overwritten by the definitive file. Pull
|
|
requests which include edits to this file in other repositories
|
|
will be rejected.
|
|
-->
|
|
|
|
# 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 aufs/overlay/devicemapper/btrfs.
|
|
|
|
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
|
|
<output suppressed>
|
|
$ 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**:
|
|
|
|
```
|
|
{% raw %}
|
|
{{ TAR STREAM }}
|
|
{% endraw %}
|
|
```
|
|
|
|
### /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**:
|
|
|
|
```
|
|
{% raw %}
|
|
{{ TAR STREAM }}
|
|
{% endraw %}
|
|
```
|
|
|
|
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.
|