Merge pull request #5580 from albers/container-completions

Improve Cobra completions for `run` and `create`

Dockerfile

@@ -8,8 +8,8 @@ ARG GO_VERSION=1.23.3
 ARG XX_VERSION=1.5.0
 ARG GOVERSIONINFO_VERSION=v1.3.0
 ARG GOTESTSUM_VERSION=v1.10.0
-ARG BUILDX_VERSION=0.17.1
+ARG BUILDX_VERSION=0.18.0
-ARG COMPOSE_VERSION=v2.29.7
+ARG COMPOSE_VERSION=v2.30.3
 
 FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx
 

cli/command/container/completion.go

@@ -44,6 +44,65 @@ var allLinuxCapabilities = sync.OnceValue(func() []string {
 	return out
 })
 
+// logDriverOptions provides the options for each built-in logging driver.
+var logDriverOptions = map[string][]string{
+	"awslogs": {
+		"max-buffer-size", "mode", "awslogs-create-group", "awslogs-credentials-endpoint", "awslogs-datetime-format",
+		"awslogs-group", "awslogs-multiline-pattern", "awslogs-region", "awslogs-stream", "tag",
+	},
+	"fluentd": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "fluentd-address", "fluentd-async",
+		"fluentd-buffer-limit", "fluentd-request-ack", "fluentd-retry-wait", "fluentd-max-retries",
+		"fluentd-sub-second-precision", "tag",
+	},
+	"gcplogs": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "gcp-log-cmd", "gcp-meta-id", "gcp-meta-name",
+		"gcp-meta-zone", "gcp-project",
+	},
+	"gelf": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "gelf-address", "gelf-compression-level",
+		"gelf-compression-type", "gelf-tcp-max-reconnect", "gelf-tcp-reconnect-delay", "tag",
+	},
+	"journald":  {"max-buffer-size", "mode", "env", "env-regex", "labels", "tag"},
+	"json-file": {"max-buffer-size", "mode", "env", "env-regex", "labels", "compress", "max-file", "max-size"},
+	"local":     {"max-buffer-size", "mode", "compress", "max-file", "max-size"},
+	"none":      {},
+	"splunk": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "splunk-caname", "splunk-capath", "splunk-format",
+		"splunk-gzip", "splunk-gzip-level", "splunk-index", "splunk-insecureskipverify", "splunk-source",
+		"splunk-sourcetype", "splunk-token", "splunk-url", "splunk-verify-connection", "tag",
+	},
+	"syslog": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "syslog-address", "syslog-facility", "syslog-format",
+		"syslog-tls-ca-cert", "syslog-tls-cert", "syslog-tls-key", "syslog-tls-skip-verify", "tag",
+	},
+}
+
+// builtInLogDrivers provides a list of the built-in logging drivers.
+var builtInLogDrivers = sync.OnceValue(func() []string {
+	drivers := make([]string, 0, len(logDriverOptions))
+	for driver := range logDriverOptions {
+		drivers = append(drivers, driver)
+	}
+	return drivers
+})
+
+// allLogDriverOptions provides all options of the built-in logging drivers.
+// The list does not contain duplicates.
+var allLogDriverOptions = sync.OnceValue(func() []string {
+	var result []string
+	seen := make(map[string]bool)
+	for driver := range logDriverOptions {
+		for _, opt := range logDriverOptions[driver] {
+			if !seen[opt] {
+				seen[opt] = true
+				result = append(result, opt)
+			}
+		}
+	}
+	return result
+})
+
 // restartPolicies is a list of all valid restart-policies..
 //
 // TODO(thaJeztah): add descriptions, and enable descriptions for our completion scripts (cobra.CompletionOptions.DisableDescriptions is currently set to "true")
@@ -54,6 +113,207 @@ var restartPolicies = []string{
 	string(container.RestartPolicyUnlessStopped),
 }
 
+// addCompletions adds the completions that `run` and `create` have in common.
+func addCompletions(cmd *cobra.Command, dockerCLI completion.APIClientProvider) {
+	_ = cmd.RegisterFlagCompletionFunc("attach", completion.FromList("stderr", "stdin", "stdout"))
+	_ = cmd.RegisterFlagCompletionFunc("cap-add", completeLinuxCapabilityNames)
+	_ = cmd.RegisterFlagCompletionFunc("cap-drop", completeLinuxCapabilityNames)
+	_ = cmd.RegisterFlagCompletionFunc("cgroupns", completeCgroupns())
+	_ = cmd.RegisterFlagCompletionFunc("env", completion.EnvVarNames)
+	_ = cmd.RegisterFlagCompletionFunc("env-file", completion.FileNames)
+	_ = cmd.RegisterFlagCompletionFunc("ipc", completeIpc(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("link", completeLink(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("log-driver", completeLogDriver(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("log-opt", completeLogOpt)
+	_ = cmd.RegisterFlagCompletionFunc("network", completion.NetworkNames(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("pid", completePid(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+	_ = cmd.RegisterFlagCompletionFunc("pull", completion.FromList(PullImageAlways, PullImageMissing, PullImageNever))
+	_ = cmd.RegisterFlagCompletionFunc("restart", completeRestartPolicies)
+	_ = cmd.RegisterFlagCompletionFunc("security-opt", completeSecurityOpt)
+	_ = cmd.RegisterFlagCompletionFunc("stop-signal", completeSignals)
+	_ = cmd.RegisterFlagCompletionFunc("storage-opt", completeStorageOpt)
+	_ = cmd.RegisterFlagCompletionFunc("ulimit", completeUlimit)
+	_ = cmd.RegisterFlagCompletionFunc("userns", completion.FromList("host"))
+	_ = cmd.RegisterFlagCompletionFunc("uts", completion.FromList("host"))
+	_ = cmd.RegisterFlagCompletionFunc("volume-driver", completeVolumeDriver(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("volumes-from", completion.ContainerNames(dockerCLI, true))
+}
+
+// completeCgroupns implements shell completion for the `--cgroupns` option of `run` and `create`.
+func completeCgroupns() completion.ValidArgsFn {
+	return completion.FromList(string(container.CgroupnsModeHost), string(container.CgroupnsModePrivate))
+}
+
+// completeDetachKeys implements shell completion for the `--detach-keys` option of `run` and `create`.
+func completeDetachKeys(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return []string{"ctrl-"}, cobra.ShellCompDirectiveNoSpace
+}
+
+// completeIpc implements shell completion for the `--ipc` option of `run` and `create`.
+// The completion is partly composite.
+func completeIpc(dockerCLI completion.APIClientProvider) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(toComplete) > 0 && strings.HasPrefix("container", toComplete) { //nolint:gocritic // not swapped, matches partly typed "container"
+			return []string{"container:"}, cobra.ShellCompDirectiveNoSpace
+		}
+		if strings.HasPrefix(toComplete, "container:") {
+			names, _ := completion.ContainerNames(dockerCLI, true)(cmd, args, toComplete)
+			return prefixWith("container:", names), cobra.ShellCompDirectiveNoFileComp
+		}
+		return []string{
+			string(container.IPCModeContainer + ":"),
+			string(container.IPCModeHost),
+			string(container.IPCModeNone),
+			string(container.IPCModePrivate),
+			string(container.IPCModeShareable),
+		}, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// completeLink implements shell completion for the `--link` option  of `run` and `create`.
+func completeLink(dockerCLI completion.APIClientProvider) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		return postfixWith(":", containerNames(dockerCLI, cmd, args, toComplete)), cobra.ShellCompDirectiveNoSpace
+	}
+}
+
+// completeLogDriver implements shell completion for the `--log-driver` option  of `run` and `create`.
+// The log drivers are collected from a call to the Info endpoint with a fallback to a hard-coded list
+// of the build-in log drivers.
+func completeLogDriver(dockerCLI completion.APIClientProvider) completion.ValidArgsFn {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		info, err := dockerCLI.Client().Info(cmd.Context())
+		if err != nil {
+			return builtInLogDrivers(), cobra.ShellCompDirectiveNoFileComp
+		}
+		drivers := info.Plugins.Log
+		return drivers, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// completeLogOpt implements shell completion for the `--log-opt` option  of `run` and `create`.
+// If the user supplied a log-driver, only options for that driver are returned.
+func completeLogOpt(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	driver, _ := cmd.Flags().GetString("log-driver")
+	if options, exists := logDriverOptions[driver]; exists {
+		return postfixWith("=", options), cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp
+	}
+	return postfixWith("=", allLogDriverOptions()), cobra.ShellCompDirectiveNoSpace
+}
+
+// completePid implements shell completion for the `--pid` option  of `run` and `create`.
+func completePid(dockerCLI completion.APIClientProvider) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(toComplete) > 0 && strings.HasPrefix("container", toComplete) { //nolint:gocritic // not swapped, matches partly typed "container"
+			return []string{"container:"}, cobra.ShellCompDirectiveNoSpace
+		}
+		if strings.HasPrefix(toComplete, "container:") {
+			names, _ := completion.ContainerNames(dockerCLI, true)(cmd, args, toComplete)
+			return prefixWith("container:", names), cobra.ShellCompDirectiveNoFileComp
+		}
+		return []string{"container:", "host"}, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// completeSecurityOpt implements shell completion for the `--security-opt` option of `run` and `create`.
+// The completion is partly composite.
+func completeSecurityOpt(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	if len(toComplete) > 0 && strings.HasPrefix("apparmor=", toComplete) { //nolint:gocritic // not swapped, matches partly typed "apparmor="
+		return []string{"apparmor="}, cobra.ShellCompDirectiveNoSpace
+	}
+	if len(toComplete) > 0 && strings.HasPrefix("label", toComplete) { //nolint:gocritic // not swapped, matches partly typed "label"
+		return []string{"label="}, cobra.ShellCompDirectiveNoSpace
+	}
+	if strings.HasPrefix(toComplete, "label=") {
+		if strings.HasPrefix(toComplete, "label=d") {
+			return []string{"label=disable"}, cobra.ShellCompDirectiveNoFileComp
+		}
+		labels := []string{"disable", "level:", "role:", "type:", "user:"}
+		return prefixWith("label=", labels), cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp
+	}
+	// length must be > 1 here so that completion of "s" falls through.
+	if len(toComplete) > 1 && strings.HasPrefix("seccomp", toComplete) { //nolint:gocritic // not swapped, matches partly typed "seccomp"
+		return []string{"seccomp="}, cobra.ShellCompDirectiveNoSpace
+	}
+	if strings.HasPrefix(toComplete, "seccomp=") {
+		return []string{"seccomp=unconfined"}, cobra.ShellCompDirectiveNoFileComp
+	}
+	return []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"}, cobra.ShellCompDirectiveNoFileComp
+}
+
+// completeStorageOpt implements shell completion for the `--storage-opt` option  of `run` and `create`.
+func completeStorageOpt(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return []string{"size="}, cobra.ShellCompDirectiveNoSpace
+}
+
+// completeUlimit implements shell completion for the `--ulimit` option of `run` and `create`.
+func completeUlimit(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	limits := []string{
+		"as",
+		"chroot",
+		"core",
+		"cpu",
+		"data",
+		"fsize",
+		"locks",
+		"maxlogins",
+		"maxsyslogins",
+		"memlock",
+		"msgqueue",
+		"nice",
+		"nofile",
+		"nproc",
+		"priority",
+		"rss",
+		"rtprio",
+		"sigpending",
+		"stack",
+	}
+	return postfixWith("=", limits), cobra.ShellCompDirectiveNoSpace
+}
+
+// completeVolumeDriver contacts the API to get the built-in and installed volume drivers.
+func completeVolumeDriver(dockerCLI completion.APIClientProvider) completion.ValidArgsFn {
+	return func(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+		info, err := dockerCLI.Client().Info(cmd.Context())
+		if err != nil {
+			// fallback: the built-in drivers
+			return []string{"local"}, cobra.ShellCompDirectiveNoFileComp
+		}
+		drivers := info.Plugins.Volume
+		return drivers, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// containerNames contacts the API to get names and optionally IDs of containers.
+// In case of an error, an empty list is returned.
+func containerNames(dockerCLI completion.APIClientProvider, cmd *cobra.Command, args []string, toComplete string) []string {
+	names, _ := completion.ContainerNames(dockerCLI, true)(cmd, args, toComplete)
+	if names == nil {
+		return []string{}
+	}
+	return names
+}
+
+// prefixWith prefixes every element in the slice with the given prefix.
+func prefixWith(prefix string, values []string) []string {
+	result := make([]string, len(values))
+	for i, v := range values {
+		result[i] = prefix + v
+	}
+	return result
+}
+
+// postfixWith appends postfix to every element in the slice.
+func postfixWith(postfix string, values []string) []string {
+	result := make([]string, len(values))
+	for i, v := range values {
+		result[i] = v + postfix
+	}
+	return result
+}
+
 func completeLinuxCapabilityNames(cmd *cobra.Command, args []string, toComplete string) (names []string, _ cobra.ShellCompDirective) {
 	return completion.FromList(allLinuxCapabilities()...)(cmd, args, toComplete)
 }

cli/command/container/completion_test.go

@@ -4,6 +4,9 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/docker/cli/internal/test"
+	"github.com/docker/cli/internal/test/builders"
+	"github.com/docker/docker/api/types/container"
 	"github.com/moby/sys/signal"
 	"github.com/spf13/cobra"
 	"gotest.tools/v3/assert"
@@ -21,6 +24,48 @@ func TestCompleteLinuxCapabilityNames(t *testing.T) {
 	}
 }
 
+func TestCompletePid(t *testing.T) {
+	tests := []struct {
+		containerListFunc   func(container.ListOptions) ([]container.Summary, error)
+		toComplete          string
+		expectedCompletions []string
+		expectedDirective   cobra.ShellCompDirective
+	}{
+		{
+			toComplete:          "",
+			expectedCompletions: []string{"container:", "host"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "c",
+			expectedCompletions: []string{"container:"},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace,
+		},
+		{
+			containerListFunc: func(container.ListOptions) ([]container.Summary, error) {
+				return []container.Summary{
+					*builders.Container("c1"),
+					*builders.Container("c2"),
+				}, nil
+			},
+			toComplete:          "container:",
+			expectedCompletions: []string{"container:c1", "container:c2"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.toComplete, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{
+				containerListFunc: tc.containerListFunc,
+			})
+			completions, directive := completePid(cli)(NewRunCommand(cli), nil, tc.toComplete)
+			assert.Check(t, is.DeepEqual(completions, tc.expectedCompletions))
+			assert.Check(t, is.Equal(directive, tc.expectedDirective))
+		})
+	}
+}
+
 func TestCompleteRestartPolicies(t *testing.T) {
 	values, directives := completeRestartPolicies(nil, nil, "")
 	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
@@ -28,6 +73,59 @@ func TestCompleteRestartPolicies(t *testing.T) {
 	assert.Check(t, is.DeepEqual(values, expected))
 }
 
+func TestCompleteSecurityOpt(t *testing.T) {
+	tests := []struct {
+		toComplete          string
+		expectedCompletions []string
+		expectedDirective   cobra.ShellCompDirective
+	}{
+		{
+			toComplete:          "",
+			expectedCompletions: []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "apparmor=",
+			expectedCompletions: []string{"apparmor="},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace,
+		},
+		{
+			toComplete:          "label=",
+			expectedCompletions: []string{"label=disable", "label=level:", "label=role:", "label=type:", "label=user:"},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete: "s",
+			// We do not filter matching completions but delegate this task to the shell script.
+			expectedCompletions: []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "se",
+			expectedCompletions: []string{"seccomp="},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace,
+		},
+		{
+			toComplete:          "seccomp=",
+			expectedCompletions: []string{"seccomp=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "sy",
+			expectedCompletions: []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.toComplete, func(t *testing.T) {
+			completions, directive := completeSecurityOpt(nil, nil, tc.toComplete)
+			assert.Check(t, is.DeepEqual(completions, tc.expectedCompletions))
+			assert.Check(t, is.Equal(directive, tc.expectedDirective))
+		})
+	}
+}
+
 func TestCompleteSignals(t *testing.T) {
 	values, directives := completeSignals(nil, nil, "")
 	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")

cli/command/container/create.go

@@ -78,16 +78,15 @@ func NewCreateCommand(dockerCli command.Cli) *cobra.Command {
 	command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
 	copts = addFlags(flags)
 
-	_ = cmd.RegisterFlagCompletionFunc("cap-add", completeLinuxCapabilityNames)
+	addCompletions(cmd, dockerCli)
-	_ = cmd.RegisterFlagCompletionFunc("cap-drop", completeLinuxCapabilityNames)
+
-	_ = cmd.RegisterFlagCompletionFunc("env", completion.EnvVarNames)
+	flags.VisitAll(func(flag *pflag.Flag) {
-	_ = cmd.RegisterFlagCompletionFunc("env-file", completion.FileNames)
+		// Set a default completion function if none was set. We don't look
-	_ = cmd.RegisterFlagCompletionFunc("network", completion.NetworkNames(dockerCli))
+		// up if it does already have one set, because Cobra does this for
-	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+		// us, and returns an error (which we ignore for this reason).
-	_ = cmd.RegisterFlagCompletionFunc("pull", completion.FromList(PullImageAlways, PullImageMissing, PullImageNever))
+		_ = cmd.RegisterFlagCompletionFunc(flag.Name, completion.NoComplete)
-	_ = cmd.RegisterFlagCompletionFunc("restart", completeRestartPolicies)
+	})
-	_ = cmd.RegisterFlagCompletionFunc("stop-signal", completeSignals)
+
-	_ = cmd.RegisterFlagCompletionFunc("volumes-from", completion.ContainerNames(dockerCli, true))
 	return cmd
 }
 

cli/command/container/run.go

@@ -69,16 +69,16 @@ func NewRunCommand(dockerCli command.Cli) *cobra.Command {
 	command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
 	copts = addFlags(flags)
 
-	_ = cmd.RegisterFlagCompletionFunc("cap-add", completeLinuxCapabilityNames)
+	_ = cmd.RegisterFlagCompletionFunc("detach-keys", completeDetachKeys)
-	_ = cmd.RegisterFlagCompletionFunc("cap-drop", completeLinuxCapabilityNames)
+	addCompletions(cmd, dockerCli)
-	_ = cmd.RegisterFlagCompletionFunc("env", completion.EnvVarNames)
+
-	_ = cmd.RegisterFlagCompletionFunc("env-file", completion.FileNames)
+	flags.VisitAll(func(flag *pflag.Flag) {
-	_ = cmd.RegisterFlagCompletionFunc("network", completion.NetworkNames(dockerCli))
+		// Set a default completion function if none was set. We don't look
-	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+		// up if it does already have one set, because Cobra does this for
-	_ = cmd.RegisterFlagCompletionFunc("pull", completion.FromList(PullImageAlways, PullImageMissing, PullImageNever))
+		// us, and returns an error (which we ignore for this reason).
-	_ = cmd.RegisterFlagCompletionFunc("restart", completeRestartPolicies)
+		_ = cmd.RegisterFlagCompletionFunc(flag.Name, completion.NoComplete)
-	_ = cmd.RegisterFlagCompletionFunc("stop-signal", completeSignals)
+	})
-	_ = cmd.RegisterFlagCompletionFunc("volumes-from", completion.ContainerNames(dockerCli, true))
+
 	return cmd
 }