From d6c74e60311c7068411f7b33f79dd0441548bd89 Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Wed, 6 Nov 2024 18:38:00 +0000 Subject: [PATCH 1/2] Emphasise distinction between docker0 and network-create options Signed-off-by: Rob Murray --- docs/reference/commandline/network_create.md | 38 ++++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md index 43c59ba3d07f..e76baa31b215 100644 --- a/docs/reference/commandline/network_create.md +++ b/docs/reference/commandline/network_create.md @@ -148,30 +148,30 @@ fails and Docker Engine returns an error. ### Bridge driver options -When creating a custom network, the default network driver (i.e. `bridge`) has -additional options that can be passed. The following are those options and the -equivalent Docker daemon flags used for docker0 bridge: - -| Option | Equivalent | Description | -|--------------------------------------------------|-------------|-------------------------------------------------------| -| `com.docker.network.bridge.name` | - | Bridge name to be used when creating the Linux bridge | -| `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` | Enable IP masquerading | -| `com.docker.network.bridge.enable_icc` | `--icc` | Enable or Disable Inter Container Connectivity | -| `com.docker.network.bridge.host_binding_ipv4` | `--ip` | Default IP when binding container ports | -| `com.docker.network.driver.mtu` | `--mtu` | Set the containers network MTU | -| `com.docker.network.container_iface_prefix` | - | Set a custom prefix for container interfaces | +When creating a custom `bridge` network, the following additional options can +be passed. Some of these have equivalent flags that can be used on the dockerd +command line or in `daemon.json` to configure the default bridge, `docker0`: + +| Network create option | Daemon option for `docker0` | Description | +|--------------------------------------------------|-----------------------------|-------------------------------------------------------| +| `com.docker.network.bridge.name` | - | Bridge name to be used when creating the Linux bridge | +| `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` | Enable IP masquerading | +| `com.docker.network.bridge.enable_icc` | `--icc` | Enable or Disable Inter Container Connectivity | +| `com.docker.network.bridge.host_binding_ipv4` | `--ip` | Default IP when binding container ports | +| `com.docker.network.driver.mtu` | `--mtu` | Set the containers network MTU | +| `com.docker.network.container_iface_prefix` | - | Set a custom prefix for container interfaces | The following arguments can be passed to `docker network create` for any network driver, again with their approximate equivalents to Docker daemon flags used for the docker0 bridge: -| Argument | Equivalent | Description | -|--------------|----------------|--------------------------------------------| -| `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | -| `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | -| `--internal` | - | Restrict external access to the network | -| `--ipv6` | `--ipv6` | Enable or disable IPv6 networking | -| `--subnet` | `--bip` | Subnet for network | +| Network create option | Daemon option for `docker0` | Description | +|-----------------------|-----------------------------|--------------------------------------------| +| `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | +| `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | +| `--internal` | - | Restrict external access to the network | +| `--ipv6` | `--ipv6` | Enable or disable IPv6 networking | +| `--subnet` | `--bip` | Subnet for network | For example, let's use `-o` or `--opt` options to specify an IP address binding when publishing ports: From afbbecd44f9ac094a2721b536ac36ce5277b0b7e Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Wed, 6 Nov 2024 18:42:11 +0000 Subject: [PATCH 2/2] Add option --ipv4 Signed-off-by: Rob Murray --- cli/command/network/create.go | 10 +++- cli/command/network/create_test.go | 54 ++++++++++++++++++++ cli/command/network/formatter.go | 6 +++ cli/command/network/formatter_test.go | 7 ++- docs/reference/commandline/network_create.md | 16 +++--- 5 files changed, 83 insertions(+), 10 deletions(-) diff --git a/cli/command/network/create.go b/cli/command/network/create.go index 69374c5880e4..e43b183190c4 100644 --- a/cli/command/network/create.go +++ b/cli/command/network/create.go @@ -24,6 +24,7 @@ type createOptions struct { driverOpts opts.MapOpts labels opts.ListOpts internal bool + ipv4 *bool ipv6 *bool attachable bool ingress bool @@ -42,7 +43,7 @@ type ipamOptions struct { } func newCreateCommand(dockerCLI command.Cli) *cobra.Command { - var ipv6 bool + var ipv4, ipv6 bool options := createOptions{ driverOpts: *opts.NewMapOpts(nil, nil), labels: opts.NewListOpts(opts.ValidateLabel), @@ -59,6 +60,9 @@ func newCreateCommand(dockerCLI command.Cli) *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { options.name = args[0] + if cmd.Flag("ipv4").Changed { + options.ipv4 = &ipv4 + } if cmd.Flag("ipv6").Changed { options.ipv6 = &ipv6 } @@ -73,7 +77,8 @@ func newCreateCommand(dockerCLI command.Cli) *cobra.Command { flags.VarP(&options.driverOpts, "opt", "o", "Set driver specific options") flags.Var(&options.labels, "label", "Set metadata on a network") flags.BoolVar(&options.internal, "internal", false, "Restrict external access to the network") - flags.BoolVar(&ipv6, "ipv6", false, "Enable or disable IPv6 networking") + flags.BoolVar(&ipv4, "ipv4", true, "Enable or disable IPv4 address assignment") + flags.BoolVar(&ipv6, "ipv6", false, "Enable or disable IPv6 address assignment") flags.BoolVar(&options.attachable, "attachable", false, "Enable manual container attachment") flags.SetAnnotation("attachable", "version", []string{"1.25"}) flags.BoolVar(&options.ingress, "ingress", false, "Create swarm routing-mesh network") @@ -113,6 +118,7 @@ func runCreate(ctx context.Context, apiClient client.NetworkAPIClient, output io Options: options.driverOpts.GetAll(), IPAM: ipamCfg, Internal: options.internal, + EnableIPv4: options.ipv4, EnableIPv6: options.ipv6, Attachable: options.attachable, Ingress: options.ingress, diff --git a/cli/command/network/create_test.go b/cli/command/network/create_test.go index 651767d65ee9..a6eea97d82db 100644 --- a/cli/command/network/create_test.go +++ b/cli/command/network/create_test.go @@ -182,6 +182,60 @@ func TestNetworkCreateWithFlags(t *testing.T) { assert.Check(t, is.Equal("banana", strings.TrimSpace(cli.OutBuffer().String()))) } +// TestNetworkCreateIPv4 verifies behavior of the "--ipv4" option. This option +// is an optional bool, and must default to "nil", not "true" or "false". +func TestNetworkCreateIPv4(t *testing.T) { + strPtr := func(val bool) *bool { return &val } + + tests := []struct { + doc, name string + flags []string + expected *bool + }{ + { + doc: "IPv4 default", + name: "ipv4-default", + expected: nil, + }, + { + doc: "IPv4 enabled", + name: "ipv4-enabled", + flags: []string{"--ipv4=true"}, + expected: strPtr(true), + }, + { + doc: "IPv4 enabled (shorthand)", + name: "ipv4-enabled-shorthand", + flags: []string{"--ipv4"}, + expected: strPtr(true), + }, + { + doc: "IPv4 disabled", + name: "ipv4-disabled", + flags: []string{"--ipv4=false"}, + expected: strPtr(false), + }, + } + + for _, tc := range tests { + t.Run(tc.doc, func(t *testing.T) { + cli := test.NewFakeCli(&fakeClient{ + networkCreateFunc: func(ctx context.Context, name string, createBody network.CreateOptions) (network.CreateResponse, error) { + assert.Check(t, is.DeepEqual(createBody.EnableIPv4, tc.expected)) + return network.CreateResponse{ID: name}, nil + }, + }) + cmd := newCreateCommand(cli) + cmd.SetArgs([]string{tc.name}) + if tc.expected != nil { + assert.Check(t, cmd.ParseFlags(tc.flags)) + } + assert.NilError(t, cmd.Execute()) + assert.Check(t, is.Equal(tc.name, strings.TrimSpace(cli.OutBuffer().String()))) + }) + } +} + // TestNetworkCreateIPv6 verifies behavior of the "--ipv6" option. This option // is an optional bool, and must default to "nil", not "true" or "false". func TestNetworkCreateIPv6(t *testing.T) { diff --git a/cli/command/network/formatter.go b/cli/command/network/formatter.go index 3e6246336192..fb2177e7ab16 100644 --- a/cli/command/network/formatter.go +++ b/cli/command/network/formatter.go @@ -13,6 +13,7 @@ const ( defaultNetworkTableFormat = "table {{.ID}}\t{{.Name}}\t{{.Driver}}\t{{.Scope}}" networkIDHeader = "NETWORK ID" + ipv4Header = "IPV4" ipv6Header = "IPV6" internalHeader = "INTERNAL" ) @@ -51,6 +52,7 @@ func FormatWrite(ctx formatter.Context, networks []network.Summary) error { "Name": formatter.NameHeader, "Driver": formatter.DriverHeader, "Scope": formatter.ScopeHeader, + "IPv4": ipv4Header, "IPv6": ipv6Header, "Internal": internalHeader, "Labels": formatter.LabelsHeader, @@ -88,6 +90,10 @@ func (c *networkContext) Scope() string { return c.n.Scope } +func (c *networkContext) IPv4() string { + return strconv.FormatBool(c.n.EnableIPv4) +} + func (c *networkContext) IPv6() string { return strconv.FormatBool(c.n.EnableIPv6) } diff --git a/cli/command/network/formatter_test.go b/cli/command/network/formatter_test.go index 018f789b1747..42afe43a1ec0 100644 --- a/cli/command/network/formatter_test.go +++ b/cli/command/network/formatter_test.go @@ -42,6 +42,9 @@ func TestNetworkContext(t *testing.T) { {networkContext{ n: network.Summary{Driver: "driver_name"}, }, "driver_name", ctx.Driver}, + {networkContext{ + n: network.Summary{EnableIPv4: true}, + }, "true", ctx.IPv4}, {networkContext{ n: network.Summary{EnableIPv6: true}, }, "true", ctx.IPv6}, @@ -180,8 +183,8 @@ func TestNetworkContextWriteJSON(t *testing.T) { {ID: "networkID2", Name: "foobar_bar"}, } expectedJSONs := []map[string]any{ - {"Driver": "", "ID": "networkID1", "IPv6": "false", "Internal": "false", "Labels": "", "Name": "foobar_baz", "Scope": "", "CreatedAt": "0001-01-01 00:00:00 +0000 UTC"}, - {"Driver": "", "ID": "networkID2", "IPv6": "false", "Internal": "false", "Labels": "", "Name": "foobar_bar", "Scope": "", "CreatedAt": "0001-01-01 00:00:00 +0000 UTC"}, + {"Driver": "", "ID": "networkID1", "IPv4": "false", "IPv6": "false", "Internal": "false", "Labels": "", "Name": "foobar_baz", "Scope": "", "CreatedAt": "0001-01-01 00:00:00 +0000 UTC"}, + {"Driver": "", "ID": "networkID2", "IPv4": "false", "IPv6": "false", "Internal": "false", "Labels": "", "Name": "foobar_bar", "Scope": "", "CreatedAt": "0001-01-01 00:00:00 +0000 UTC"}, } out := bytes.NewBufferString("") diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md index e76baa31b215..4d3fa3c4a91a 100644 --- a/docs/reference/commandline/network_create.md +++ b/docs/reference/commandline/network_create.md @@ -18,7 +18,8 @@ Create a network | `--ip-range` | `stringSlice` | | Allocate container ip from a sub-range | | `--ipam-driver` | `string` | `default` | IP Address Management Driver | | `--ipam-opt` | `map` | `map[]` | Set IPAM driver specific options | -| `--ipv6` | `bool` | | Enable or disable IPv6 networking | +| `--ipv4` | `bool` | `true` | Enable or disable IPv4 address assignment | +| `--ipv6` | `bool` | | Enable or disable IPv6 address assignment | | `--label` | `list` | | Set metadata on a network | | `-o`, `--opt` | `map` | `map[]` | Set driver specific options | | `--scope` | `string` | | Control the network's scope | @@ -167,11 +168,14 @@ flags used for the docker0 bridge: | Network create option | Daemon option for `docker0` | Description | |-----------------------|-----------------------------|--------------------------------------------| -| `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | -| `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | -| `--internal` | - | Restrict external access to the network | -| `--ipv6` | `--ipv6` | Enable or disable IPv6 networking | -| `--subnet` | `--bip` | Subnet for network | +| Network create option | Daemon option for `docker0` | Description | +|-----------------------|-----------------------------------|--------------------------------------------| +| `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | +| `--ip-range` | `--fixed-cidr`, `--fixed-cidr-v6` | Allocate IP addresses from a range | +| `--internal` | - | Restrict external access to the network | +| `--ipv4` | - | Enable or disable IPv4 address assignment | +| `--ipv6` | `--ipv6` | Enable or disable IPv6 address assignment | +| `--subnet` | `--bip`, `--bip6` | Subnet for network | For example, let's use `-o` or `--opt` options to specify an IP address binding when publishing ports: