mirror of https://github.com/docker/cli.git
Removing CLI plugins API documentation from official documentation as it is now deprecated.
Adding depreciation notice. Signed-off-by: Silvin Lubecki <silvin.lubecki@docker.com>
This commit is contained in:
Silvin Lubecki
parent
13ee065e95
commit
459c6082f8
|
|
@ -10,7 +10,7 @@ const (
|
|||
MetadataSubcommandName = "docker-cli-plugin-metadata"
|
||||
)
|
||||
|
||||
// Metadata provided by the plugin. See docs/extend/cli_plugins.md for canonical information.
|
||||
// Metadata provided by the plugin.
|
||||
type Metadata struct {
|
||||
// SchemaVersion describes the version of this struct. Mandatory, must be "0.1.0"
|
||||
SchemaVersion string `json:",omitempty"`
|
||||
|
|
|
|||
|
|
@ -50,6 +50,7 @@ The table below provides an overview of the current status of deprecated feature
|
|||
|
||||
Status | Feature | Deprecated | Remove
|
||||
-----------|------------------------------------------------------------------------------------------------------------------------------------|------------|------------
|
||||
Deprecated | [CLI plugins support](#cli-plugins-support) | v20.03.0 | -
|
||||
Deprecated | [Pushing and pulling with image manifest v2 schema 1](#pushing-and-pulling-with-image-manifest-v2-schema-1) | v19.03.0 | v20.03.0
|
||||
Removed | [`docker engine` subcommands](#docker-engine-subcommands) | v19.03.0 | v20.03.0
|
||||
Removed | [Top-level `docker deploy` subcommand (experimental)](#top-level-docker-deploy-subcommand-experimental) | v19.03.0 | v20.03.0
|
||||
|
|
@ -87,6 +88,11 @@ Removed | [`--api-enable-cors` flag on `dockerd`](#--api-enable-cors-flag-on-
|
|||
Removed | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit) | v0.10.0 | v1.13.0
|
||||
Removed | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import) | v0.6.7 | v1.12.0
|
||||
|
||||
### CLI plugins support
|
||||
|
||||
**Deprecated in Release: v20.03.0**
|
||||
|
||||
CLI Plugin API is now marked as deprecated.
|
||||
|
||||
### Pushing and pulling with image manifest v2 schema 1
|
||||
|
||||
|
|
|
|||
|
|
@ -1,124 +0,0 @@
|
|||
---
|
||||
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`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Plugins are expected to make use of existing global configuration
|
||||
where it makes sense and likewise to consider extending the global
|
||||
configuration (by patching `docker/cli` to add new fields) where that
|
||||
is sensible.
|
||||
|
||||
Where plugins unavoidably require specific configuration the
|
||||
`.plugins.«name»` key in the global `config.json` is reserved for
|
||||
their use. However the preference should be for shared/global
|
||||
configuration whenever that makes sense.
|
||||
|
||||
## Connecting to the docker engine
|
||||
|
||||
For consistency plugins should prefer to dial the engine by using the
|
||||
`system dial-stdio` subcommand of the main Docker CLI binary.
|
||||
|
||||
To facilitate this plugins will be executed with the
|
||||
`$DOCKER_CLI_PLUGIN_ORIGINAL_CLI_COMMAND` environment variable
|
||||
pointing back to the main Docker CLI binary.
|
||||
|
||||
All global options (everything from after the binary name up to, but
|
||||
not including, the primary entry point subcommand name) should be
|
||||
passed back to the CLI.
|
||||
|
||||
## 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 either `%ProgramData%\Docker\cli-plugins` or
|
||||
`%ProgramFiles%\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