cli/command/container: implement docker run --annotation

For moby/moby PR 45025 (Docker v24, API v1.43).

`docker run --annotation foo=bar` is similar to `podman run --annotation foo=bar`,
however, unlike Podman, Docker implementation also accepts an annotation with an empty value.
(`docker run --annotation foo`)

Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>

cli/command/container/opts.go

@@ -123,6 +123,7 @@ type containerOptions struct {
 	runtime            string
 	autoRemove         bool
 	init               bool
+	annotations        *opts.MapOpts
 
 	Image string
 	Args  []string
@@ -163,6 +164,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
 		ulimits:           opts.NewUlimitOpt(nil),
 		volumes:           opts.NewListOpts(nil),
 		volumesFrom:       opts.NewListOpts(nil),
+		annotations:       opts.NewMapOpts(nil, nil),
 	}
 
 	// General purpose flags
@@ -297,6 +299,10 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
 
 	flags.BoolVar(&copts.init, "init", false, "Run an init inside the container that forwards signals and reaps processes")
 	flags.SetAnnotation("init", "version", []string{"1.25"})
+
+	flags.Var(copts.annotations, "annotation", "Add an annotation to the container (passed through to the OCI runtime)")
+	flags.SetAnnotation("annotation", "version", []string{"1.43"})
+
 	return copts
 }
 
@@ -654,6 +660,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 		Mounts:         mounts,
 		MaskedPaths:    maskedPaths,
 		ReadonlyPaths:  readonlyPaths,
+		Annotations:    copts.annotations.GetAll(),
 	}
 
 	if copts.autoRemove && !hostConfig.RestartPolicy.IsNone() {

contrib/completion/bash/docker

@@ -1888,6 +1888,7 @@ _docker_container_run() {
 _docker_container_run_and_create() {
 	local options_with_args="
 		--add-host
+		--annotation
 		--attach -a
 		--blkio-weight
 		--blkio-weight-device

contrib/completion/fish/docker.fish

@@ -178,6 +178,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from cp' -l help -d 'Print u
 # create
 complete -c docker -f -n '__fish_docker_no_subcommand' -a create -d 'Create a new container'
 complete -c docker -A -f -n '__fish_seen_subcommand_from create' -l add-host -d 'Add a custom host-to-IP mapping (host:ip)'
+complete -c docker -A -f -n '__fish_seen_subcommand_from create' -l annotation -d 'Add an annotation to the container (passed through to the OCI runtime)'
 complete -c docker -A -f -n '__fish_seen_subcommand_from create' -s a -l attach -d 'Attach to STDIN, STDOUT or STDERR.'
 complete -c docker -A -f -n '__fish_seen_subcommand_from create' -l blkio-weight -d 'Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)'
 complete -c docker -A -f -n '__fish_seen_subcommand_from create' -l blkio-weight-device -d 'Block IO weight (relative device weight)'
@@ -453,6 +454,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from rmi' -a '(__fish_print_
 
 # run
 complete -c docker -f -n '__fish_docker_no_subcommand' -a run -d 'Create and run a new container from an image'
+complete -c docker -A -f -n '__fish_seen_subcommand_from run' -l annotation -d 'Add an annotation to the container (passed through to the OCI runtime)'
 complete -c docker -A -f -n '__fish_seen_subcommand_from run' -s a -l attach -d 'Attach to STDIN, STDOUT or STDERR.'
 complete -c docker -A -f -n '__fish_seen_subcommand_from run' -l add-host -d 'Add a custom host-to-IP mapping (host:ip)'
 complete -c docker -A -f -n '__fish_seen_subcommand_from run' -s c -l cpu-shares -d 'CPU shares (relative weight)'

contrib/completion/zsh/_docker

@@ -602,6 +602,7 @@ __docker_container_subcommand() {
     opts_create_run=(
         "($help -a --attach)"{-a=,--attach=}"[Attach to stdin, stdout or stderr]:device:(STDIN STDOUT STDERR)"
         "($help)*--add-host=[Add a custom host-to-IP mapping]:host\:ip mapping: "
+        "($help)*--annotation=[Add an annotation to the container (passed through to the OCI runtime)]:annotations: "
         "($help)*--blkio-weight-device=[Block IO (relative device weight)]:device:Block IO weight: "
         "($help)*--cap-add=[Add Linux capabilities]:capability: "
         "($help)*--cap-drop=[Drop Linux capabilities]:capability: "

docs/reference/commandline/run.md

@@ -12,6 +12,7 @@ Create and run a new container from an image
 | Name                                          | Type          | Default   | Description                                                                                                                                                                                                                                                                                                      |
 |:----------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [`--add-host`](#add-host)                     | `list`        |           | Add a custom host-to-IP mapping (host:ip)                                                                                                                                                                                                                                                                        |
+| `--annotation`                                | `map`         |           | Add an annotation to the container (passed through to the OCI runtime)                                                                                                                                                                                                                                                                                     |
 | [`-a`](#attach), [`--attach`](#attach)        | `list`        |           | Attach to STDIN, STDOUT or STDERR                                                                                                                                                                                                                                                                                |
 | `--blkio-weight`                              | `uint16`      | `0`       | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)                                                                                                                                                                                                                                     |
 | `--blkio-weight-device`                       | `list`        |           | Block IO weight (relative device weight)                                                                                                                                                                                                                                                                         |

man/docker-run.1.md

@@ -7,6 +7,7 @@ docker-run - Create and run a new container from an image
 **docker run**
 [**-a**|**--attach**[=*[]*]]
 [**--add-host**[=*[]*]]
+[**--annotation**[=*[]*]]
 [**--blkio-weight**[=*[BLKIO-WEIGHT]*]]
 [**--blkio-weight-device**[=*[]*]]
 [**--cpu-shares**[=*0*]]
@@ -125,6 +126,11 @@ each of stdin, stdout, and stderr.
    Add a line to /etc/hosts. The format is hostname:ip.  The **--add-host**
 option can be set multiple times.
 
+**--annotation**=[]
+   Add an annotation to the container (passed through to the OCI runtime).
+
+   The annotations are provided to the OCI runtime.
+
 **--blkio-weight**=*0*
    Block IO weight (relative weight) accepts a weight value between 10 and 1000.