From 02677bc06e34d475fa8966f851fee291f639c96c Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Sat, 28 Jan 2017 16:54:32 -0800 Subject: [PATCH] Add docker plugin upgrade This allows a plugin to be upgraded without requiring to uninstall/reinstall a plugin. Since plugin resources (e.g. volumes) are tied to a plugin ID, this is important to ensure resources aren't lost. The plugin must be disabled while upgrading (errors out if enabled). This does not add any convenience flags for automatically disabling/re-enabling the plugin during before/after upgrade. Since an upgrade may change requested permissions, the user is required to accept permissions just like `docker plugin install`. Signed-off-by: Brian Goff --- docs/reference/commandline/plugin_create.md | 1 + docs/reference/commandline/plugin_disable.md | 1 + docs/reference/commandline/plugin_enable.md | 1 + docs/reference/commandline/plugin_inspect.md | 2 + docs/reference/commandline/plugin_install.md | 1 + docs/reference/commandline/plugin_ls.md | 10 ++- docs/reference/commandline/plugin_push.md | 1 + docs/reference/commandline/plugin_rm.md | 1 + docs/reference/commandline/plugin_upgrade.md | 84 ++++++++++++++++++++ 9 files changed, 98 insertions(+), 4 deletions(-) create mode 100644 docs/reference/commandline/plugin_upgrade.md diff --git a/docs/reference/commandline/plugin_create.md b/docs/reference/commandline/plugin_create.md index df3b2cccc8..fa74d31c39 100644 --- a/docs/reference/commandline/plugin_create.md +++ b/docs/reference/commandline/plugin_create.md @@ -58,3 +58,4 @@ The plugin can subsequently be enabled for local use or pushed to the public reg * [plugin push](plugin_push.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_disable.md b/docs/reference/commandline/plugin_disable.md index e8d16c4253..451f1ace9c 100644 --- a/docs/reference/commandline/plugin_disable.md +++ b/docs/reference/commandline/plugin_disable.md @@ -63,3 +63,4 @@ ID NAME TAG DESCRIP * [plugin push](plugin_push.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_enable.md b/docs/reference/commandline/plugin_enable.md index 060592ef07..df8bee3af5 100644 --- a/docs/reference/commandline/plugin_enable.md +++ b/docs/reference/commandline/plugin_enable.md @@ -62,3 +62,4 @@ ID NAME TAG DESCRIP * [plugin push](plugin_push.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md index d40cd40e75..fdcc030c43 100644 --- a/docs/reference/commandline/plugin_inspect.md +++ b/docs/reference/commandline/plugin_inspect.md @@ -37,6 +37,7 @@ $ docker plugin inspect tiborvass/sample-volume-plugin:latest { "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21", "Name": "tiborvass/sample-volume-plugin:latest", + "PluginReference": "tiborvas/sample-volume-plugin:latest", "Enabled": true, "Config": { "Mounts": [ @@ -160,3 +161,4 @@ $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest * [plugin push](plugin_push.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_install.md b/docs/reference/commandline/plugin_install.md index b94f78a912..4cba32cf8b 100644 --- a/docs/reference/commandline/plugin_install.md +++ b/docs/reference/commandline/plugin_install.md @@ -69,3 +69,4 @@ ID NAME TAG DESCRIPTION * [plugin push](plugin_push.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_ls.md b/docs/reference/commandline/plugin_ls.md index c018dec813..b0224a00f8 100644 --- a/docs/reference/commandline/plugin_ls.md +++ b/docs/reference/commandline/plugin_ls.md @@ -83,10 +83,11 @@ Valid placeholders for the Go template are listed below: Placeholder | Description ---------------|------------------------------------------------------------------------------------------ -`.ID` | Plugin ID -`.Name` | Plugin name -`.Description` | Plugin description -`.Enabled` | Whether plugin is enabled or not +`.ID` | Plugin ID +`.Name` | Plugin name +`.Description` | Plugin description +`.Enabled` | Whether plugin is enabled or not +`.PluginReference` | The reference used to push/pull from a registry When using the `--format` option, the `plugin ls` command will either output the data exactly as the template declares or, when using the @@ -111,3 +112,4 @@ $ docker plugin ls --format "{{.ID}}: {{.Name}}" * [plugin push](plugin_push.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_push.md b/docs/reference/commandline/plugin_push.md index d6f326d6de..89a0a0bb0e 100644 --- a/docs/reference/commandline/plugin_push.md +++ b/docs/reference/commandline/plugin_push.md @@ -48,3 +48,4 @@ $ docker plugin push user/plugin * [plugin ls](plugin_ls.md) * [plugin rm](plugin_rm.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_rm.md b/docs/reference/commandline/plugin_rm.md index 31029324b6..323ce83f3c 100644 --- a/docs/reference/commandline/plugin_rm.md +++ b/docs/reference/commandline/plugin_rm.md @@ -53,3 +53,4 @@ tiborvass/sample-volume-plugin * [plugin ls](plugin_ls.md) * [plugin push](plugin_push.md) * [plugin set](plugin_set.md) +* [plugin upgrade](plugin_upgrade.md) diff --git a/docs/reference/commandline/plugin_upgrade.md b/docs/reference/commandline/plugin_upgrade.md new file mode 100644 index 0000000000..20efc577aa --- /dev/null +++ b/docs/reference/commandline/plugin_upgrade.md @@ -0,0 +1,84 @@ +--- +title: "plugin upgrade" +description: "the plugin upgrade command description and usage" +keywords: "plugin, upgrade" +--- + + + +# plugin upgrade + +```markdown +Usage: docker plugin upgrade [OPTIONS] PLUGIN [REMOTE] + +Upgrade a plugin + +Options: + --disable-content-trust Skip image verification (default true) + --grant-all-permissions Grant all permissions necessary to run the plugin + --help Print usage + --skip-remote-check Do not check if specified remote plugin matches existing plugin image +``` + +Upgrades an existing plugin to the specified remote plugin image. If no remote +is specified, Docker will re-pull the current image and use the updated version. +All existing references to the plugin will continue to work. +The plugin must be disabled before running the upgrade. + +The following example installs `vieus/sshfs` plugin, uses it to create and use +a volume, then upgrades the plugin. + +```bash +$ docker plugin install vieux/sshfs DEBUG=1 + +Plugin "vieux/sshfs:next" is requesting the following privileges: + - network: [host] + - device: [/dev/fuse] + - capabilities: [CAP_SYS_ADMIN] +Do you grant the above permissions? [y/N] y +vieux/sshfs:next + +$ docker volume create -d vieux/sshfs:next -o sshcmd=root@1.2.3.4:/tmp/shared -o password=XXX sshvolume +sshvolume +$ docker run -it -v sshvolume:/data alpine sh -c "touch /data/hello" +$ docker plugin disable -f vieux/sshfs:next +viex/sshfs:next + +# Here docker volume ls doesn't show 'sshfsvolume', since the plugin is disabled +$ docker volume ls +DRIVER VOLUME NAME + +$ docker plugin upgrade vieux/sshfs:next vieux/sshfs:next +Plugin "vieux/sshfs:next" is requesting the following privileges: + - network: [host] + - device: [/dev/fuse] + - capabilities: [CAP_SYS_ADMIN] +Do you grant the above permissions? [y/N] y +Upgrade plugin vieux/sshfs:next to vieux/sshfs:next +$ docker plugin enable vieux/sshfs:next +viex/sshfs:next +$ docker volume ls +DRIVER VOLUME NAME +viuex/sshfs:next sshvolume +$ docker run -it -v sshvolume:/data alpine sh -c "ls /data" +hello +``` + +## Related information + +* [plugin create](plugin_create.md) +* [plugin disable](plugin_disable.md) +* [plugin enable](plugin_enable.md) +* [plugin inspect](plugin_inspect.md) +* [plugin install](plugin_install.md) +* [plugin ls](plugin_ls.md) +* [plugin push](plugin_push.md) +* [plugin rm](plugin_rm.md) +* [plugin set](plugin_set.md)