github.com/gdevillele/moby@v1.13.0/docs/extend/index.md (about)

     1  ---
     2  description: Develop and use a plugin with the managed plugin system
     3  keywords: "API, Usage, plugins, documentation, developer"
     4  title: Managed plugin system
     5  ---
     6  
     7  <!-- This file is maintained within the docker/docker Github
     8       repository at https://github.com/docker/docker/. Make all
     9       pull requests against that repo. If you see this file in
    10       another repository, consider it read-only there, as it will
    11       periodically be overwritten by the definitive file. Pull
    12       requests which include edits to this file in other repositories
    13       will be rejected.
    14  -->
    15  
    16  # Docker Engine managed plugin system
    17  
    18  * [Installing and using a plugin](index.md#installing-and-using-a-plugin)
    19  * [Developing a plugin](index.md#developing-a-plugin)
    20  
    21  Docker Engine's plugins system allows you to install, start, stop, and remove
    22  plugins using Docker Engine. This mechanism is currently only available for
    23  volume drivers, but more plugin driver types will be available in future releases.
    24  
    25  For information about the legacy plugin system available in Docker Engine 1.12
    26  and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md).
    27  
    28  > **Note**: Docker Engine managed plugins are currently not supported
    29  on Windows daemons.
    30  
    31  ## Installing and using a plugin
    32  
    33  Plugins are distributed as Docker images and can be hosted on Docker Hub or on
    34  a private registry.
    35  
    36  To install a plugin, use the `docker plugin install` command, which pulls the
    37  plugin from Docker hub or your private registry, prompts you to grant
    38  permissions or capabilities if necessary, and enables the plugin.
    39  
    40  To check the status of installed plugins, use the `docker plugin ls` command.
    41  Plugins that start successfully are listed as enabled in the output.
    42  
    43  After a plugin is installed, you can use it as an option for another Docker
    44  operation, such as creating a volume.
    45  
    46  In the following example, you install the `sshfs` plugin, verify that it is
    47  enabled, and use it to create a volume.
    48  
    49  1.  Install the `sshfs` plugin.
    50  
    51      ```bash
    52      $ docker plugin install vieux/sshfs
    53  
    54      Plugin "vieux/sshfs" is requesting the following privileges:
    55      - network: [host]
    56      - capabilities: [CAP_SYS_ADMIN]
    57      Do you grant the above permissions? [y/N] y
    58  
    59      vieux/sshfs
    60      ```
    61  
    62      The plugin requests 2 privileges:
    63      - It needs access to the `host` network.
    64      - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run
    65      the `mount` command.
    66  
    67  2.  Check that the plugin is enabled in the output of `docker plugin ls`.
    68  
    69      ```bash
    70      $ docker plugin ls
    71  
    72      ID                    NAME                  TAG                 DESCRIPTION                   ENABLED
    73      69553ca1d789          vieux/sshfs           latest              the `sshfs` plugin            true
    74      ```
    75  
    76  3.  Create a volume using the plugin.
    77      This example mounts the `/remote` directory on host `1.2.3.4` into a
    78      volume named `sshvolume`. This volume can now be mounted into containers.
    79  
    80      ```bash
    81      $ docker volume create \
    82        -d vieux/sshfs \
    83        --name sshvolume \
    84        -o sshcmd=user@1.2.3.4:/remote
    85  
    86      sshvolume
    87      ```
    88  4.  Verify that the volume was created successfully.
    89  
    90      ```bash
    91      $ docker volume ls
    92  
    93      DRIVER              NAME
    94      vieux/sshfs         sshvolume
    95      ```
    96  
    97  5.  Start a container that uses the volume `sshvolume`.
    98  
    99      ```bash
   100      $ docker run -v sshvolume:/data busybox ls /data
   101  
   102      <content of /remote on machine 1.2.3.4>
   103      ```
   104  
   105  To disable a plugin, use the `docker plugin disable` command. To completely
   106  remove it, use the `docker plugin remove` command. For other available
   107  commands and options, see the
   108  [command line reference](../reference/commandline/index.md).
   109  
   110  ## Developing a plugin
   111  
   112  #### The rootfs directory
   113  The `rootfs` directory represents the root filesystem of the plugin. In this
   114  example, it was created from a Dockerfile:
   115  
   116  >**Note:** The `/run/docker/plugins` directory is mandatory inside of the
   117  plugin's filesystem for docker to communicate with the plugin.
   118  
   119  ```bash
   120  $ git clone https://github.com/vieux/docker-volume-sshfs
   121  $ cd docker-volume-sshfs
   122  $ docker build -t rootfsimage .
   123  $ id=$(docker create rootfsimage true) # id was cd851ce43a403 when the image was created
   124  $ sudo mkdir -p myplugin/rootfs
   125  $ sudo docker export "$id" | sudo tar -x -C myplugin/rootfs
   126  $ docker rm -vf "$id"
   127  $ docker rmi rootfsimage
   128  ```
   129  
   130  #### The config.json file
   131  
   132  The `config.json` file describes the plugin. See the [plugins config reference](config.md).
   133  
   134  Consider the following `config.json` file.
   135  
   136  ```json
   137  {
   138  	"description": "sshFS plugin for Docker",
   139  	"documentation": "https://docs.docker.com/engine/extend/plugins/",
   140  	"entrypoint": ["/go/bin/docker-volume-sshfs"],
   141  	"network": {
   142  		   "type": "host"
   143  		   },
   144  	"interface" : {
   145  		   "types": ["docker.volumedriver/1.0"],
   146  		   "socket": "sshfs.sock"
   147  	},
   148  	"capabilities": ["CAP_SYS_ADMIN"]
   149  }
   150  ```
   151  
   152  This plugin is a volume driver. It requires a `host` network and the
   153  `CAP_SYS_ADMIN` capability. It depends upon the `/go/bin/docker-volume-sshfs`
   154  entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate
   155  with Docker Engine. This plugin has no runtime parameters.
   156  
   157  ### Creating the plugin
   158  
   159  A new plugin can be created by running
   160  `docker plugin create <plugin-name> ./path/to/plugin/data` where the plugin
   161  data contains a plugin configuration file `config.json` and a root filesystem
   162  in subdirectory `rootfs`. 
   163  
   164  After that the plugin `<plugin-name>` will show up in `docker plugin ls`.
   165  Plugins can be pushed to remote registries with
   166  `docker plugin push <plugin-name>`.