docker cli experimental flag for plugins

[andrewhsu]

Change request...

Have the docker cli experimental flag in ~/.docker/config.json:

{ "experimental": "enabled" }

Control whether experimental docker cli plugins are enabled.

This would imply a need for plugins to be marked as experimental if desired.

Related: #1564

[andrewhsu]

After going over feedback from implementation PR, I'm putting some constraints on this change request to help with the flow of developers installing and cli plugins...

Requirements:

1. docker-ce packages install cli experimental packages by default but disabled
2. user of docker-ce must explicitly enable experimental plugins that come installed by default
3. user of docker-ce can install a developer build of plugin without having to globally enable all experimental features (this constraint is subtle, but a new one that is needed to help with developer workflow of plugins)

Implementation:

1. if a cli plugin has -experimental as a suffix in its binary filename, then only enable the plugin if ~/.docker/config.json has experimental flag set. update: see github comment below

In this way, a user of docker-ce can install a foobar cli plugin by making sure it does not have -experimental in its filename as a suffix and be able to use it straight away.

[andrewhsu]

Talked through some of the implementation steps with @tiborvass and having a scan of directories seem the way to go for keeping binaries separate.

So, if the client config ~/.docker/config.json has experimental flag set then the binaries for the plugin will be searched in the following order:

1. cliPluginsExtraDirs directories specified in ~/.docker/config.json
2. the ~/.docker/cli-plugins directory
3. defaultSystemPluginDirs
4. cliPluginsExtraDirs directories specified in ~/.docker/config.json with -experimental appended
5. the ~/.docker/cli-plugins-experimental directory
6. defaultSystemPluginDirs with -experimental appended

If the client config ~/.docker/config.json does not experimental flag set, then the search directory list for finding a plugin will just be:

1. cliPluginsExtraDirs directories specified in ~/.docker/config.json
2. the ~/.docker/cli-plugins directory
3. defaultSystemPluginDirs

[mat007]

Is the -experimental suffix in the file names, the folder names or both?

[gtardif]

Also, in the steps above, it seems that the -experimental filename suffix will work in cliPluginsExtraDirs and defaultSystemPluginDirs, but not in ~/.docker/cli-plugins. Any reason for this ?

[thaJeztah]

Some quick blurbs from discussions I had;

A. Separate directories for experimental plugins:

• might complicate things for Docker Desktop (in combination with version packs)
• could be more problematic when upgrading plugins from experimental to stable (as in: old plugin must be removed, and cannot be overwritten)
• what is the preferred order of preference if a plugin is installed both in an experimental and non-experimental directory? (should the experimental plugin be active, or the non-experimental version?)

B. Using a -experimental suffix:

• might be less problematic for Docker Desktop (input welcome on that!)
• same problem with upgrading
• same problem with order of preference (although possibly easier to spot the problem as both will be in the same directory)

C. Using experimental: true metadata

• plugin author can control if a plugin is marked "experimental"
• very briefly discussed with @tiborvass: the "experimental" bit could be a compile-time option, so that:
  • someone building a plugin from source (and manually installing a plugin, thus a conscious decision) would get a plugin without the "experimental" bit set
  • plugin author can control if the default is "experimental" or "non-experimental"
  • the packager (docker, inc.) can set experimental: true when building plugins that ship with Docker

I think the compile-time option would address @tonistiigi's (and (IMO), valid, concern raised in #1898 (comment) that someone explicitly compiling and installing a plugin should not have to enable "experimental" to make the plugin work, as they know what they're doing)

C.1. Also related to experimental:true metadata:

• The YAML docs have an experimental property, which would be useful so that the documentation can call out experimental plugins (and commands)
• That property is based on experimental annotations set on commands and flags

We could base the metadata on the "root" command of a plugin having the experimental annotation set, so that:

• a plugin with "experimental" set on the root-command would be marked experimental as a whole (and skipped)
• a plugin without the annotation set on the root command would show up / be enabled, but subcommands (or flags) with the annotation can be hidden/disabled if the CLI is not configured with experimental enabled.
• the YAML docs would reflect the correct status.

(note that the "experimental" status is inherited by subcommands, so if the root-command has "experimental" set; all subcommands of that root will also be marked "experimental")

D. Alternative: use plugin version as indication for stability

• Assuming plugins use SemVer (need to look up if we made that a requirement)
• On Docker; skip plugins that are < 1.0.0 unless "experimental" is set
• Single source of truth (as in: version marks stability)
• 👍 Plugin author is in charge of marking a plugin "stable"
• 👎 Someone manually installing a plugin would still need to enable "experimental"
• 👍 No changes needed in plugins or metadata
• 👍 👎 packager / Docker has no control over deciding if a plugin is considered stable from their perspective

[guillaumerose]

E. Don't change anything. Let distributions ship what they want.

• Keep only one directory for experimental plugins and display them all. No change in metadata.
• Debian packages, Docker Desktop and other distributions choose what they want to provide.
• Release each plugin individually. Let the distribution do the right aggregation.

Distributors are responsible of what they provide to end users. They manage the changelog and have the responsability to ship something that work and to support it for 2 years. Let them do their work.

[tiborvass]

@mat007 @gtardif -experimental as part of the current proposal was to be appended to the folder names only. (There was a variant with -experimental only on filenames without changes to directories but it complicates things a lot on the cli and requires the same amount of work on Desktop).

A user installing a plugin themselves is already an act of opting in, they shouldn't need to enable experimental on top of it, bringing in a whole bunch of new commands they didn't ask for. For this same reason, < 1.0.0 cannot mean experimental.

I'm fine with having just one agreed-upon directory for experimental instead of doubling the number of directories, including user directories.

could be more problematic when upgrading plugins from experimental to stable (as in: old plugin must be removed, and cannot be overwritten)

Whatever package managers do today. And they do remove binaries they installed. Even if you've overwritten them. And I'm fine not considering the case where people put things in system paths.

what is the preferred order of preference if a plugin is installed both in an experimental and non-experimental directory? (should the experimental plugin be active, or the non-experimental version?)

Currently, the non-experimental takes precedence over experimental.

might complicate things for Docker Desktop (in combination with version packs)

This is what I don't quite understand. Isn't it just putting things in a different directory for now and when things graduate from experimental, adding a "remove binary from experimental folder" line?

[thaJeztah]

This is what I don't quite understand. Isn't it just putting things in a different directory for now and when things graduate from experimental, adding a "remove binary from experimental folder" line?

I think the complication (or at least: additional work) is that docker desktop creates symlinks for all plugins. In case of version-packs, different versions would have a different set of plugins (or same plugins but either experimental or non-experimental). I don't have insight in the amount of additional work required though

[tiborvass]

Agree with @guillaumerose on letting distros ship what they want. I just hope they don't want to support plugins that aren't ready. My personal favorite option would be to not ship any plugins and let users download them easily, documented via docs. But I guess that ship has sailed.

[tiborvass]

what is the preferred order of preference if a plugin is installed both in an experimental and non-experimental directory? (should the experimental plugin be active, or the non-experimental version?)

Currently, the non-experimental takes precedence over experimental.

Upon @ijc's request I changed precedence to:

• cliPluginsExtraDirs
• cliPluginsExtraDirs with -experimental appended to each directory
• ~/.docker/cli-plugins
• ~/.docker/cli-plugins-experimental
• defaultSystemPluginDirs
• defaultSystemPluginDirs with -experimental appended to each directory

[andrewhsu]

For the packaging side of things, to get docker-ce and docker desktop managing cli plugins as experimental, it has become more clear that #1898 seems like the fastest path to ground.

I'll open a separate issue to track proper treatment of lifecycle management of docker cli plugins which is the thing that we want to really get to for installing cli plugins, update cli plugins and have plugin authors promote to GA.

[andrewhsu]

change request for docker cli plugin lifecycle management #1904