mirror of https://github.com/docker/cli.git
Documentation on writing a plugin
Signed-off-by: Ian Campbell <ijc@docker.com>
This commit is contained in:
Ian Campbell
parent
1c576e9043
commit
609dcb9152
|
|
@ -10,7 +10,7 @@ const (
|
|||
MetadataSubcommandName = "docker-cli-plugin-metadata"
|
||||
)
|
||||
|
||||
// Metadata provided by the plugin
|
||||
// Metadata provided by the plugin. See docs/extend/cli_plugins.md for canonical information.
|
||||
type Metadata struct {
|
||||
// SchemaVersion describes the version of this struct. Mandatory, must be "0.1.0"
|
||||
SchemaVersion string `json:",omitempty"`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
description: "Writing Docker CLI Plugins"
|
||||
keywords: "docker, cli plugin"
|
||||
---
|
||||
|
||||
<!-- 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.
|
||||
-->
|
||||
|
||||
# Docker CLI Plugin Spec
|
||||
|
||||
The `docker` CLI supports adding additional top-level subcommands as
|
||||
additional out-of-process commands which can be installed
|
||||
independently. These plugins run on the client side and should not be
|
||||
confused with "plugins" which run on the server.
|
||||
|
||||
This document contains information for authors of such plugins.
|
||||
|
||||
## Requirements for CLI Plugins
|
||||
|
||||
### Naming
|
||||
|
||||
A valid CLI plugin name consists only of lower case letters `a-z`
|
||||
and the digits `0-9`. The leading character must be a letter. A valid
|
||||
name therefore would match the regex `^[a-z][a-z0-9]*$`.
|
||||
|
||||
The binary implementing a plugin must be named `docker-$name` where
|
||||
`$name` is the name of the plugin. On Windows a `.exe` suffix is
|
||||
mandatory.
|
||||
|
||||
## Required sub-commands
|
||||
|
||||
A CLI plugin must support being invoked in at least these two ways:
|
||||
|
||||
* `docker-$name docker-cli-plugin-metadata` -- outputs metadata about
|
||||
the plugin.
|
||||
* `docker-$name [GLOBAL OPTIONS] $name [OPTIONS AND FURTHER SUB
|
||||
COMMANDS]` -- the primary entry point to the plugin's functionality.
|
||||
|
||||
A plugin may implement other subcommands but these will never be
|
||||
invoked by the current Docker CLI. However doing so is strongly
|
||||
discouraged: new subcommands may be added in the future without
|
||||
consideration for additional non-specified subcommands which may be
|
||||
used by plugins in the field.
|
||||
|
||||
### The `docker-cli-plugin-metadata` subcommand
|
||||
|
||||
When invoked in this manner the plugin must produce a JSON object
|
||||
(and nothing else) on its standard output and exit success (0).
|
||||
|
||||
The JSON object has the following defined keys:
|
||||
* `SchemaVersion` (_string_) mandatory: must contain precisely "0.1.0".
|
||||
* `Vendor` (_string_) mandatory: contains the name of the plugin vendor/author. May be truncated to 11 characters in some display contexts.
|
||||
* `ShortDescription` (_string_) optional: a short description of the plugin, suitable for a single line help message.
|
||||
* `Version` (_string_) optional: the version of the plugin, this is considered to be an opaque string by the core and therefore has no restrictions on its syntax.
|
||||
* `URL` (_string_) optional: a pointer to the plugin's web page.
|
||||
|
||||
A binary which does not correctly output the metadata
|
||||
(e.g. syntactically invalid, missing mandatory keys etc) is not
|
||||
considered a valid CLI plugin and will not be run.
|
||||
|
||||
### The primary entry point subcommand
|
||||
|
||||
This is the entry point for actually running the plugin. It maybe have
|
||||
options or further subcommands.
|
||||
|
||||
#### Required global options
|
||||
|
||||
A plugin is required to support all of the global options of the
|
||||
top-level CLI, i.e. those listed by `man docker 1` with the exception
|
||||
of `-v`.
|
||||
|
||||
## Installation
|
||||
|
||||
Plugins distributed in packages for system wide installation on
|
||||
Unix(-like) systems should be installed in either
|
||||
`/usr/lib/docker/cli-plugins` or `/usr/libexec/docker/cli-plugins`
|
||||
depending on which of `/usr/lib` and `/usr/libexec` is usual on that
|
||||
system. System Administrators may also choose to manually install into
|
||||
the `/usr/local/lib` or `/usr/local/libexec` equivalents but packages
|
||||
should not do so.
|
||||
|
||||
Plugins distributed on Windows for system wide installation should be
|
||||
installed in `%PROGRAMDATA%\Docker\cli-plugins`.
|
||||
|
||||
User's may on all systems install plugins into `~/.docker/cli-plugins`.
|
||||
|
||||
## Implementing a plugin in Go
|
||||
|
||||
When writing a plugin in Go the easiest way to meet the above
|
||||
requirements is to simply call the
|
||||
`github.com/docker/cli/cli-plugins/plugin.Run` method from your `main`
|
||||
function to instantiate the plugin.
|
||||
Loading…
Reference in New Issue