DockerCLI/docs/reference/commandline
Sebastiaan van Stijn 190c64b415
Service cap-add/cap-drop: improve handling of combinations and special "ALL" value
When creating and updating services, we need to avoid unneeded service churn.

The interaction of separate lists to "add" and "drop" capabilities, a special
("ALL") capability, as well as a "relaxed" format for accepted capabilities
(case-insensitive, `CAP_` prefix optional) make this rather involved.

This patch updates how we handle `--cap-add` / `--cap-drop` when  _creating_ as
well as _updating_, with the following rules/assumptions applied:

- both existing (service spec) and new (values passed through flags or in
  the compose-file) are normalized and de-duplicated before use.
- the special "ALL" capability is equivalent to "all capabilities" and taken
  into account when normalizing capabilities. Combining "ALL" capabilities
  and other capabilities is therefore equivalent to just specifying "ALL".
- adding capabilities takes precedence over dropping, which means that if
  a capability is both set to be "dropped" and to be "added", it is removed
  from the list to "drop".
- the final lists should be sorted and normalized to reduce service churn
- no validation of capabilities is handled by the client. Validation is
  delegated to the daemon/server.

When deploying a service using a docker-compose file, the docker-compose file
is *mostly* handled as being "declarative". However, many of the issues outlined
above also apply to compose-files, so similar handling is applied to compose
files as well to prevent service churn.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2020-09-08 14:38:35 +02:00
..
attach.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
build.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
cli.md Split up environment variable documentation between cli and dockerd 2020-06-11 13:54:39 +02:00
commit.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
container.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
container_prune.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
context_create.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_export.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_import.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_inspect.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_ls.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_rm.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_update.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
context_use.md docs: fix, and touch-up "docker context" docs 2020-05-07 13:53:25 +02:00
cp.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
create.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
diff.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
dockerd.md docs: update for cgroup v2 and rootless 2020-06-24 19:24:54 +09:00
events.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
exec.md Added env-file flag to docker exec 2020-06-29 18:32:44 -04:00
export.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
history.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
image.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
image_prune.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
images.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
import.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
index.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
info.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
inspect.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
kill.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
load.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
login.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
logout.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
logs.md fix docs, completion and docker service 2020-08-06 17:37:08 +03:00
manifest.md Added support for setting OS version in docker manifest annotate. 2020-06-12 12:04:03 -07:00
network.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
network_connect.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
network_create.md Add container_iface_prefix option to documentation 2020-04-24 12:39:24 +02:00
network_disconnect.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
network_inspect.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
network_ls.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
network_prune.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
network_rm.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
node.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
node_demote.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
node_inspect.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
node_ls.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
node_promote.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
node_ps.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
node_rm.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
node_update.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
pause.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
plugin.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
plugin_create.md docs: fix example output for docker plugin ls 2020-06-18 16:37:36 +02:00
plugin_disable.md docs: fix example output for docker plugin ls 2020-06-18 16:37:36 +02:00
plugin_enable.md docs: fix example output for docker plugin ls 2020-06-18 16:37:36 +02:00
plugin_inspect.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
plugin_install.md docs: fix example output for docker plugin ls 2020-06-18 16:37:36 +02:00
plugin_ls.md docs: fix example output for docker plugin ls 2020-06-18 16:37:36 +02:00
plugin_push.md docs: fix example output for docker plugin ls 2020-06-18 16:37:36 +02:00
plugin_rm.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
plugin_set.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
plugin_upgrade.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
port.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
ps.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
pull.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
push.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
rename.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
restart.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
rm.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
rmi.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
run.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
save.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
search.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
secret.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
secret_create.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
secret_inspect.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
secret_ls.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
secret_rm.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
service.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
service_create.md Service cap-add/cap-drop: improve handling of combinations and special "ALL" value 2020-09-08 14:38:35 +02:00
service_inspect.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
service_logs.md fix docs, completion and docker service 2020-08-06 17:37:08 +03:00
service_ls.md Add jobs support to CLI 2020-04-24 11:22:10 -05:00
service_ps.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
service_rm.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
service_rollback.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
service_scale.md Add jobs support to CLI 2020-04-24 11:22:10 -05:00
service_update.md Service cap-add/cap-drop: improve handling of combinations and special "ALL" value 2020-09-08 14:38:35 +02:00
stack.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
stack_deploy.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
stack_ls.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
stack_ps.md list state `ready` for filtering in stack_ps.md 2020-06-10 12:31:25 +02:00
stack_rm.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
stack_services.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
start.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
stats.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
stop.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
swarm.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
swarm_ca.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
swarm_init.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
swarm_join-token.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
swarm_join.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
swarm_leave.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
swarm_unlock-key.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
swarm_unlock.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
swarm_update.md reference docs: reformat notes 2020-04-19 17:52:26 +02:00
system.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
system_df.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
system_events.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
system_prune.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
tag.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
top.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
trust_inspect.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
trust_key_generate.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
trust_key_load.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
trust_revoke.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
trust_sign.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
trust_signer_add.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
trust_signer_remove.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
unpause.md remove unneeded comment from reference files 2020-03-19 15:15:23 +01:00
update.md deprecate `docker run --kernel-memory` 2020-07-24 20:56:15 +09:00
version.md docker version: add "context" to output 2020-05-07 14:07:15 +02:00
volume.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
volume_create.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
volume_inspect.md docs: more Markdown touch-ups 2020-05-11 17:32:52 +02:00
volume_ls.md docs/reference: explain "colon" 2020-04-19 17:53:17 +02:00
volume_prune.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
volume_rm.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00
wait.md reference docs: fix broken links and markdown touch-ups 2020-04-19 17:13:07 +02:00