Merge pull request #28186 from yongtang/27567-follow-up-dns-options

Add `--dns-option` to `docker run` and hide `--dns-opt`

cli/command/service/create.go

@@ -43,7 +43,7 @@ func newCreateCommand(dockerCli *command.DockerCli) *cobra.Command {
 	flags.VarP(&opts.endpoint.ports, flagPublish, "p", "Publish a port as a node port")
 	flags.Var(&opts.groups, flagGroup, "Set one or more supplementary user groups for the container")
 	flags.Var(&opts.dns, flagDNS, "Set custom DNS servers")
-	flags.Var(&opts.dnsOptions, flagDNSOptions, "Set DNS options")
+	flags.Var(&opts.dnsOption, flagDNSOption, "Set DNS options")
 	flags.Var(&opts.dnsSearch, flagDNSSearch, "Set custom DNS search domains")
 
 	flags.SetInterspersed(false)

cli/command/service/opts.go

@@ -413,7 +413,7 @@ type serviceOptions struct {
 	mounts          opts.MountOpt
 	dns             opts.ListOpts
 	dnsSearch       opts.ListOpts
-	dnsOptions      opts.ListOpts
+	dnsOption       opts.ListOpts
 
 	resources resourceOptions
 	stopGrace DurationOpt
@@ -445,12 +445,12 @@ func newServiceOptions() *serviceOptions {
 		endpoint: endpointOptions{
 			ports: opts.NewListOpts(ValidatePort),
 		},
-		groups:     opts.NewListOpts(nil),
-		logDriver:  newLogDriverOptions(),
-		dns:        opts.NewListOpts(opts.ValidateIPAddress),
-		dnsOptions: opts.NewListOpts(nil),
-		dnsSearch:  opts.NewListOpts(opts.ValidateDNSSearch),
-		networks:   opts.NewListOpts(nil),
+		groups:    opts.NewListOpts(nil),
+		logDriver: newLogDriverOptions(),
+		dns:       opts.NewListOpts(opts.ValidateIPAddress),
+		dnsOption: opts.NewListOpts(nil),
+		dnsSearch: opts.NewListOpts(opts.ValidateDNSSearch),
+		networks:  opts.NewListOpts(nil),
 	}
 }
 
@@ -496,7 +496,7 @@ func (opts *serviceOptions) ToService() (swarm.ServiceSpec, error) {
 				DNSConfig: &swarm.DNSConfig{
 					Nameservers: opts.dns.GetAll(),
 					Search:      opts.dnsSearch.GetAll(),
-					Options:     opts.dnsOptions.GetAll(),
+					Options:     opts.dnsOption.GetAll(),
 				},
 				StopGracePeriod: opts.stopGrace.Value(),
 				Secrets:         nil,
@@ -597,9 +597,9 @@ const (
 	flagDNS                   = "dns"
 	flagDNSRemove             = "dns-rm"
 	flagDNSAdd                = "dns-add"
-	flagDNSOptions            = "dns-options"
-	flagDNSOptionsRemove      = "dns-options-rm"
-	flagDNSOptionsAdd         = "dns-options-add"
+	flagDNSOption             = "dns-option"
+	flagDNSOptionRemove       = "dns-option-rm"
+	flagDNSOptionAdd          = "dns-option-add"
 	flagDNSSearch             = "dns-search"
 	flagDNSSearchRemove       = "dns-search-rm"
 	flagDNSSearchAdd          = "dns-search-add"

cli/command/service/update.go

@@ -49,9 +49,9 @@ func newUpdateCommand(dockerCli *command.DockerCli) *cobra.Command {
 	flags.Var(newListOptsVar(), flagMountRemove, "Remove a mount by its target path")
 	flags.Var(newListOptsVar(), flagPublishRemove, "Remove a published port by its target port")
 	flags.Var(newListOptsVar(), flagConstraintRemove, "Remove a constraint")
-	flags.Var(newListOptsVar(), flagDNSRemove, "Remove custom DNS servers")
-	flags.Var(newListOptsVar(), flagDNSOptionsRemove, "Remove DNS options")
-	flags.Var(newListOptsVar(), flagDNSSearchRemove, "Remove DNS search domains")
+	flags.Var(newListOptsVar(), flagDNSRemove, "Remove a custom DNS server")
+	flags.Var(newListOptsVar(), flagDNSOptionRemove, "Remove a DNS option")
+	flags.Var(newListOptsVar(), flagDNSSearchRemove, "Remove a DNS search domain")
 	flags.Var(&opts.labels, flagLabelAdd, "Add or update a service label")
 	flags.Var(&opts.containerLabels, flagContainerLabelAdd, "Add or update a container label")
 	flags.Var(&opts.env, flagEnvAdd, "Add or update an environment variable")
@@ -61,9 +61,9 @@ func newUpdateCommand(dockerCli *command.DockerCli) *cobra.Command {
 	flags.Var(&opts.constraints, flagConstraintAdd, "Add or update a placement constraint")
 	flags.Var(&opts.endpoint.ports, flagPublishAdd, "Add or update a published port")
 	flags.Var(&opts.groups, flagGroupAdd, "Add an additional supplementary user group to the container")
-	flags.Var(&opts.dns, flagDNSAdd, "Add or update custom DNS servers")
-	flags.Var(&opts.dnsOptions, flagDNSOptionsAdd, "Add or update DNS options")
-	flags.Var(&opts.dnsSearch, flagDNSSearchAdd, "Add or update custom DNS search domains")
+	flags.Var(&opts.dns, flagDNSAdd, "Add or update a custom DNS server")
+	flags.Var(&opts.dnsOption, flagDNSOptionAdd, "Add or update a DNS option")
+	flags.Var(&opts.dnsSearch, flagDNSSearchAdd, "Add or update a custom DNS search domain")
 
 	return cmd
 }
@@ -274,7 +274,7 @@ func updateService(flags *pflag.FlagSet, spec *swarm.ServiceSpec) error {
 		}
 	}
 
-	if anyChanged(flags, flagDNSAdd, flagDNSRemove, flagDNSOptionsAdd, flagDNSOptionsRemove, flagDNSSearchAdd, flagDNSSearchRemove) {
+	if anyChanged(flags, flagDNSAdd, flagDNSRemove, flagDNSOptionAdd, flagDNSOptionRemove, flagDNSSearchAdd, flagDNSSearchRemove) {
 		if cspec.DNSConfig == nil {
 			cspec.DNSConfig = &swarm.DNSConfig{}
 		}
@@ -586,12 +586,12 @@ func updateDNSConfig(flags *pflag.FlagSet, config **swarm.DNSConfig) error {
 	sort.Strings(newConfig.Search)
 
 	options := (*config).Options
-	if flags.Changed(flagDNSOptionsAdd) {
-		values := flags.Lookup(flagDNSOptionsAdd).Value.(*opts.ListOpts).GetAll()
+	if flags.Changed(flagDNSOptionAdd) {
+		values := flags.Lookup(flagDNSOptionAdd).Value.(*opts.ListOpts).GetAll()
 		options = append(options, values...)
 	}
 	options = removeDuplicates(options)
-	toRemove = buildToRemoveSet(flags, flagDNSOptionsRemove)
+	toRemove = buildToRemoveSet(flags, flagDNSOptionRemove)
 	for _, option := range options {
 		if _, exists := toRemove[option]; !exists {
 			newConfig.Options = append(newConfig.Options, option)

cli/command/service/update_test.go

@@ -142,8 +142,8 @@ func TestUpdateDNSConfig(t *testing.T) {
 	// Invalid dns search domain
 	assert.Error(t, flags.Set("dns-search-add", "example$com"), "example$com is not a valid domain")
 
-	flags.Set("dns-options-add", "ndots:9")
-	flags.Set("dns-options-rm", "timeout:3")
+	flags.Set("dns-option-add", "ndots:9")
+	flags.Set("dns-option-rm", "timeout:3")
 
 	config := &swarm.DNSConfig{
 		Nameservers: []string{"3.3.3.3", "5.5.5.5"},

contrib/completion/bash/docker

@@ -1248,7 +1248,7 @@ _docker_container_run() {
 		--device-write-bps
 		--device-write-iops
 		--dns
-		--dns-opt
+		--dns-option
 		--dns-search
 		--entrypoint
 		--env -e

contrib/completion/zsh/_docker

@@ -531,7 +531,7 @@ __docker_container_subcommand() {
         "($help)*--device-write-iops=[Limit the write rate (IO per second) to a device]:device:IO rate: "
         "($help)--disable-content-trust[Skip image verification]"
         "($help)*--dns=[Custom DNS servers]:DNS server: "
-        "($help)*--dns-opt=[Custom DNS options]:DNS option: "
+        "($help)*--dns-option=[Custom DNS options]:DNS option: "
         "($help)*--dns-search=[Custom DNS search domains]:DNS domains: "
         "($help)*"{-e=,--env=}"[Environment variables]:environment variable: "
         "($help)--entrypoint=[Overwrite the default entrypoint of the image]:entry point: "

docs/reference/commandline/create.md

@@ -50,7 +50,7 @@ Options:
       --device-write-iops value     Limit write rate (IO per second) to a device (default [])
       --disable-content-trust       Skip image verification (default true)
       --dns value                   Set custom DNS servers (default [])
-      --dns-opt value               Set DNS options (default [])
+      --dns-option value            Set DNS options (default [])
       --dns-search value            Set custom DNS search domains (default [])
       --entrypoint string           Overwrite the default ENTRYPOINT of the image
   -e, --env value                   Set environment variables (default [])

docs/reference/commandline/run.md

@@ -54,7 +54,7 @@ Options:
       --device-write-iops value     Limit write rate (IO per second) to a device (default [])
       --disable-content-trust       Skip image verification (default true)
       --dns value                   Set custom DNS servers (default [])
-      --dns-opt value               Set DNS options (default [])
+      --dns-option value            Set DNS options (default [])
       --dns-search value            Set custom DNS search domains (default [])
       --entrypoint string           Overwrite the default ENTRYPOINT of the image
   -e, --env value                   Set environment variables (default [])

docs/reference/commandline/service_create.md

@@ -24,7 +24,7 @@ Options:
       --constraint list                  Placement constraints (default [])
       --container-label list             Container labels (default [])
       --dns list                         Set custom DNS servers (default [])
-      --dns-options list                 Set DNS options (default [])
+      --dns-option list                  Set DNS options (default [])
       --dns-search list                  Set custom DNS search domains (default [])
       --endpoint-mode string             Endpoint mode (vip or dnsrr)
   -e, --env list                         Set environment variables (default [])

docs/reference/commandline/service_update.md

@@ -26,12 +26,12 @@ Options:
       --constraint-rm list               Remove a constraint (default [])
       --container-label-add list         Add or update a container label (default [])
       --container-label-rm list          Remove a container label by its key (default [])
-      --dns-add list                     Add or update custom DNS servers (default [])
-      --dns-options-add list             Add or update DNS options (default [])
-      --dns-options-rm list              Remove DNS options (default [])
-      --dns-rm list                      Remove custom DNS servers (default [])
-      --dns-search-add list              Add or update custom DNS search domains (default [])
-      --dns-search-rm list               Remove DNS search domains (default [])
+      --dns-add list                     Add or update a custom DNS server (default [])
+      --dns-option-add list              Add or update a DNS option (default [])
+      --dns-option-rm list               Remove a DNS option (default [])
+      --dns-rm list                      Remove a custom DNS server (default [])
+      --dns-search-add list              Add or update a custom DNS search domain (default [])
+      --dns-search-rm list               Remove a DNS search domain (default [])
       --endpoint-mode string             Endpoint mode (vip or dnsrr)
       --env-add list                     Add or update an environment variable (default [])
       --env-rm list                      Remove an environment variable (default [])

docs/reference/run.md

@@ -388,7 +388,7 @@ network mode a container has its own UTS namespace by default. As such
 `--hostname` is allowed in `host` network mode and will only change the
 hostname inside the container.
 Similar to `--hostname`, the `--add-host`, `--dns`, `--dns-search`, and
-`--dns-opt` options can be used in `host` network mode. These options update
+`--dns-option` options can be used in `host` network mode. These options update
 `/etc/hosts` or `/etc/resolv.conf` inside the container. No change are made to
 `/etc/hosts` and `/etc/resolv.conf` on the host.
 
@@ -407,7 +407,7 @@ or a High Performance Web Server.
 With the network set to `container` a container will share the
 network stack of another container.  The other container's name must be
 provided in the format of `--network container:<name|id>`. Note that `--add-host`
-`--hostname` `--dns` `--dns-search` `--dns-opt` and `--mac-address` are
+`--hostname` `--dns` `--dns-search` `--dns-option` and `--mac-address` are
 invalid in `container` netmode, and `--publish` `--publish-all` `--expose` are
 also invalid in `container` netmode.
 

integration-cli/docker_cli_swarm_test.go

@@ -811,7 +811,7 @@ func (s *DockerSwarmSuite) TestDNSConfig(c *check.C) {
 
 	// Create a service
 	name := "top"
-	_, err := d.Cmd("service", "create", "--name", name, "--dns=1.2.3.4", "--dns-search=example.com", "--dns-options=timeout:3", "busybox", "top")
+	_, err := d.Cmd("service", "create", "--name", name, "--dns=1.2.3.4", "--dns-search=example.com", "--dns-option=timeout:3", "busybox", "top")
 	c.Assert(err, checker.IsNil)
 
 	// Make sure task has been deployed.
@@ -844,7 +844,7 @@ func (s *DockerSwarmSuite) TestDNSConfigUpdate(c *check.C) {
 	// Make sure task has been deployed.
 	waitAndAssert(c, defaultReconciliationTimeout, d.checkActiveContainerCount, checker.Equals, 1)
 
-	_, err = d.Cmd("service", "update", "--dns-add=1.2.3.4", "--dns-search-add=example.com", "--dns-options-add=timeout:3", name)
+	_, err = d.Cmd("service", "update", "--dns-add=1.2.3.4", "--dns-search-add=example.com", "--dns-option-add=timeout:3", name)
 	c.Assert(err, checker.IsNil)
 
 	out, err := d.Cmd("service", "inspect", "--format", "{{ .Spec.TaskTemplate.ContainerSpec.DNSConfig }}", name)

man/docker-create.1.md

@@ -31,7 +31,7 @@ docker-create - Create a new container
 [**--device-write-iops**[=*[]*]]
 [**--dns**[=*[]*]]
 [**--dns-search**[=*[]*]]
-[**--dns-opt**[=*[]*]]
+[**--dns-option**[=*[]*]]
 [**-e**|**--env**[=*[]*]]
 [**--entrypoint**[=*ENTRYPOINT*]]
 [**--env-file**[=*[]*]]
@@ -190,7 +190,7 @@ two memory nodes.
 **--dns**=[]
    Set custom DNS servers
 
-**--dns-opt**=[]
+**--dns-option**=[]
    Set custom DNS options
 
 **--dns-search**=[]

man/docker-run.1.md

@@ -32,7 +32,7 @@ docker-run - Run a command in a new container
 [**--device-write-bps**[=*[]*]]
 [**--device-write-iops**[=*[]*]]
 [**--dns**[=*[]*]]
-[**--dns-opt**[=*[]*]]
+[**--dns-option**[=*[]*]]
 [**--dns-search**[=*[]*]]
 [**-e**|**--env**[=*[]*]]
 [**--entrypoint**[=*ENTRYPOINT*]]
@@ -260,7 +260,7 @@ See **config-json(5)** for documentation on using a configuration file.
 **--dns-search**=[]
    Set custom DNS search domains (Use --dns-search=. if you don't wish to set the search domain)
 
-**--dns-opt**=[]
+**--dns-option**=[]
    Set custom DNS options
 
 **--dns**=[]

runconfig/opts/parse.go

@@ -187,7 +187,11 @@ func AddFlags(flags *pflag.FlagSet) *ContainerOptions {
 	// Network and port publishing flag
 	flags.Var(&copts.extraHosts, "add-host", "Add a custom host-to-IP mapping (host:ip)")
 	flags.Var(&copts.dns, "dns", "Set custom DNS servers")
+	// We allow for both "--dns-opt" and "--dns-option", although the latter is the recommended way.
+	// This is to be consistent with service create/update
 	flags.Var(&copts.dnsOptions, "dns-opt", "Set DNS options")
+	flags.Var(&copts.dnsOptions, "dns-option", "Set DNS options")
+	flags.MarkHidden("dns-opt")
 	flags.Var(&copts.dnsSearch, "dns-search", "Set custom DNS search domains")
 	flags.Var(&copts.expose, "expose", "Expose a port or a range of ports")
 	flags.StringVar(&copts.ipv4Address, "ip", "", "Container IPv4 address (e.g. 172.30.100.104)")