run, create, connect: add support for gw-priority

Signed-off-by: Albin Kerouanton <albinker@gmail.com>

cli/command/container/opts.go

@@ -858,7 +858,9 @@ func parseNetworkAttachmentOpt(ep opts.NetworkAttachmentOpts) (*networktypes.End
 		}
 	}
 
-	epConfig := &networktypes.EndpointSettings{}
+	epConfig := &networktypes.EndpointSettings{
+		GwPriority: ep.GwPriority,
+	}
 	epConfig.Aliases = append(epConfig.Aliases, ep.Aliases...)
 	if len(ep.DriverOpts) > 0 {
 		epConfig.DriverOpts = make(map[string]string)

cli/command/network/connect.go

@@ -23,6 +23,7 @@ type connectOptions struct {
 	aliases      []string
 	linklocalips []string
 	driverOpts   []string
+	gwPriority   int
 }
 
 func newConnectCommand(dockerCLI command.Cli) *cobra.Command {
@@ -55,6 +56,7 @@ func newConnectCommand(dockerCLI command.Cli) *cobra.Command {
 	flags.StringSliceVar(&options.aliases, "alias", []string{}, "Add network-scoped alias for the container")
 	flags.StringSliceVar(&options.linklocalips, "link-local-ip", []string{}, "Add a link-local address for the container")
 	flags.StringSliceVar(&options.driverOpts, "driver-opt", []string{}, "driver options for the network")
+	flags.IntVar(&options.gwPriority, "gw-priority", 0, "Highest gw-priority provides the default gateway. Accepts positive and negative values.")
 	return cmd
 }
 
@@ -73,6 +75,7 @@ func runConnect(ctx context.Context, apiClient client.NetworkAPIClient, options
 		Links:      options.links.GetAll(),
 		Aliases:    options.aliases,
 		DriverOpts: driverOpts,
+		GwPriority: options.gwPriority,
 	})
 }
 

cli/command/network/connect_test.go

@@ -56,6 +56,7 @@ func TestNetworkConnectWithFlags(t *testing.T) {
 			"driveropt1": "optval1,optval2",
 			"driveropt2": "optval4",
 		},
+		GwPriority: 100,
 	}
 	cli := test.NewFakeCli(&fakeClient{
 		networkConnectFunc: func(ctx context.Context, networkID, container string, config *network.EndpointSettings) error {
@@ -76,6 +77,7 @@ func TestNetworkConnectWithFlags(t *testing.T) {
 		{"ip6", "fdef:f401:8da0:1234::5678"},
 		{"link", "otherctr"},
 		{"link-local-ip", "169.254.42.42"},
+		{"gw-priority", "100"},
 	} {
 		err := cmd.Flags().Set(opt.name, opt.value)
 		assert.Check(t, err)

docs/reference/commandline/container_run.md

@@ -750,7 +750,7 @@ for the `--network` flag. Comma-separated options that can be specified in the e
 `--network` syntax are:
 
 | Option          | Top-level Equivalent                  | Description                                                                             |
-|-----------------|---------------------------------------|-------------------------------------------------|
+|-----------------|---------------------------------------|-----------------------------------------------------------------------------------------|
 | `name`          |                                       | The name of the network (mandatory)                                                     |
 | `alias`         | `--network-alias`                     | Add network-scoped alias for the container                                              |
 | `ip`            | `--ip`                                | IPv4 address (e.g., 172.30.100.104)                                                     |
@@ -758,6 +758,7 @@ for the `--network` flag. Comma-separated options that can be specified in the e
 | `mac-address`   | `--mac-address`                       | Container MAC address (e.g., 92:d0:c6:0a:29:33)                                         |
 | `link-local-ip` | `--link-local-ip`                     | Container IPv4/IPv6 link-local addresses                                                |
 | `driver-opt`    | `docker network connect --driver-opt` | Network driver options                                                                  |
+| `gw-priority`   |                                       | Highest gw-priority provides the default gateway. Accepts positive and negative values. |
 
 ```console
 $ docker network create --subnet 192.0.2.0/24 my-net1

docs/reference/commandline/network_connect.md

@@ -6,9 +6,10 @@ Connect a container to a network
 ### Options
 
 | Name                | Type          | Default | Description                                                                             |
-|:--------------------|:--------------|:--------|:-------------------------------------------|
+|:--------------------|:--------------|:--------|:----------------------------------------------------------------------------------------|
 | [`--alias`](#alias) | `stringSlice` |         | Add network-scoped alias for the container                                              |
 | `--driver-opt`      | `stringSlice` |         | driver options for the network                                                          |
+| `--gw-priority`     | `int`         | `0`     | Highest gw-priority provides the default gateway. Accepts positive and negative values. |
 | [`--ip`](#ip)       | `string`      |         | IPv4 address (e.g., `172.30.100.104`)                                                   |
 | `--ip6`             | `string`      |         | IPv6 address (e.g., `2001:db8::33`)                                                     |
 | [`--link`](#link)   | `list`        |         | Add link to another container                                                           |

opts/network.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"regexp"
+	"strconv"
 	"strings"
 )
 
@@ -16,6 +17,7 @@ const (
 	networkOptMacAddress  = "mac-address"
 	networkOptLinkLocalIP = "link-local-ip"
 	driverOpt             = "driver-opt"
+	gwPriorityOpt         = "gw-priority"
 )
 
 // NetworkAttachmentOpts represents the network options for endpoint creation
@@ -28,6 +30,7 @@ type NetworkAttachmentOpts struct {
 	IPv6Address  string
 	LinkLocalIPs []string
 	MacAddress   string
+	GwPriority   int
 }
 
 // NetworkOpt represents a network config in swarm mode.
@@ -83,6 +86,11 @@ func (n *NetworkOpt) Set(value string) error { //nolint:gocyclo
 					netOpt.DriverOpts = make(map[string]string)
 				}
 				netOpt.DriverOpts[key] = val
+			case gwPriorityOpt:
+				netOpt.GwPriority, err = strconv.Atoi(val)
+				if err != nil {
+					return fmt.Errorf("invalid gw-priority: %w", err)
+				}
 			default:
 				return errors.New("invalid field key " + key)
 			}

opts/network_test.go

@@ -112,6 +112,16 @@ func TestNetworkOptAdvancedSyntax(t *testing.T) {
 				},
 			},
 		},
+		{
+			value: "name=docknet1,gw-priority=10",
+			expected: []NetworkAttachmentOpts{
+				{
+					Target:     "docknet1",
+					Aliases:    []string{},
+					GwPriority: 10,
+				},
+			},
+		},
 	}
 	for _, tc := range testCases {
 		t.Run(tc.value, func(t *testing.T) {

vendor.mod

@@ -13,7 +13,7 @@ require (
 	github.com/distribution/reference v0.6.0
 	github.com/docker/cli-docs-tool v0.8.0
 	github.com/docker/distribution v2.8.3+incompatible
-	github.com/docker/docker v27.0.2-0.20241120142749-e5c2b5e10d68+incompatible // master (v-next)
+	github.com/docker/docker v27.0.2-0.20241202115249-87fbd9cd3b37+incompatible // master (v-next)
 	github.com/docker/docker-credential-helpers v0.8.2
 	github.com/docker/go-connections v0.5.0
 	github.com/docker/go-units v0.5.0

vendor.sum

@@ -51,8 +51,8 @@ github.com/docker/cli-docs-tool v0.8.0/go.mod h1:8TQQ3E7mOXoYUs811LiPdUnAhXrcVsB
 github.com/docker/distribution v2.7.1+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
 github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk=
 github.com/docker/distribution v2.8.3+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
-github.com/docker/docker v27.0.2-0.20241120142749-e5c2b5e10d68+incompatible h1:ZWh4HhdUCagAd3S+gsFPOobHbc562obYFSrz3irGSsU=
+github.com/docker/docker v27.0.2-0.20241202115249-87fbd9cd3b37+incompatible h1:Ct0/s+pkUCDPBsQmLVHnBEas8OlTRxNvDXdSa6Y2PfE=
-github.com/docker/docker v27.0.2-0.20241120142749-e5c2b5e10d68+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/docker v27.0.2-0.20241202115249-87fbd9cd3b37+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
 github.com/docker/docker-credential-helpers v0.8.2 h1:bX3YxiGzFP5sOXWc3bTPEXdEaZSeVMrFgOr3T+zrFAo=
 github.com/docker/docker-credential-helpers v0.8.2/go.mod h1:P3ci7E3lwkZg6XiHdRKft1KckHiO9a2rNtyFbZ/ry9M=
 github.com/docker/go v1.5.1-1.0.20160303222718-d30aec9fd63c h1:lzqkGL9b3znc+ZUgi7FlLnqjQhcXxkNM/quxIjBVMD0=

vendor/github.com/docker/docker/api/swagger.yaml

@@ -2927,6 +2927,16 @@ definitions:
         example:
           com.example.some-label: "some-value"
           com.example.some-other-label: "some-other-value"
+      GwPriority:
+        description: |
+          This property determines which endpoint will provide the default
+          gateway for a container. The endpoint with the highest priority will
+          be used. If multiple endpoints have the same priority, endpoints are
+          lexicographically sorted based on their network name, and the one
+          that sorts first is picked.
+        type: "number"
+        example:
+          - 10
 
       # Operational data
       NetworkID:
@@ -10910,6 +10920,7 @@ paths:
                   IPv4Address: "172.24.56.89"
                   IPv6Address: "2001:db8::5689"
                 MacAddress: "02:42:ac:12:05:02"
+                Priority: 100
       tags: ["Network"]
 
   /networks/{id}/disconnect:

vendor/github.com/docker/docker/api/types/network/endpoint.go

@@ -19,6 +19,7 @@ type EndpointSettings struct {
 	// generated address).
 	MacAddress string
 	DriverOpts map[string]string
+	GwPriority int
 	// Operational data
 	NetworkID           string
 	EndpointID          string

vendor/github.com/docker/docker/registry/service.go

@@ -103,7 +103,6 @@ func (s *Service) ResolveRepository(name reference.Named) (*RepositoryInfo, erro
 type APIEndpoint struct {
 	Mirror                         bool
 	URL                            *url.URL
-	Version                        APIVersion // Deprecated: v1 registries are deprecated, and endpoints are always v2.
 	AllowNondistributableArtifacts bool
 	Official                       bool
 	TrimHostname                   bool

vendor/github.com/docker/docker/registry/service_v2.go

@@ -25,7 +25,6 @@ func (s *Service) lookupV2Endpoints(hostname string) (endpoints []APIEndpoint, e
 			}
 			endpoints = append(endpoints, APIEndpoint{
 				URL:          mirrorURL,
-				Version:      APIVersion2, //nolint:staticcheck // ignore SA1019 (Version is deprecated) to allow potential consumers to transition.
 				Mirror:       true,
 				TrimHostname: true,
 				TLSConfig:    mirrorTLSConfig,
@@ -33,7 +32,6 @@ func (s *Service) lookupV2Endpoints(hostname string) (endpoints []APIEndpoint, e
 		}
 		endpoints = append(endpoints, APIEndpoint{
 			URL:          DefaultV2Registry,
-			Version:      APIVersion2, //nolint:staticcheck // ignore SA1019 (Version is deprecated) to allow potential consumers to transition.
 			Official:     true,
 			TrimHostname: true,
 			TLSConfig:    tlsconfig.ServerDefault(),
@@ -55,7 +53,6 @@ func (s *Service) lookupV2Endpoints(hostname string) (endpoints []APIEndpoint, e
 				Scheme: "https",
 				Host:   hostname,
 			},
-			Version:                        APIVersion2, //nolint:staticcheck // ignore SA1019 (Version is deprecated) to allow potential consumers to transition.
 			AllowNondistributableArtifacts: ana,
 			TrimHostname:                   true,
 			TLSConfig:                      tlsConfig,
@@ -68,7 +65,6 @@ func (s *Service) lookupV2Endpoints(hostname string) (endpoints []APIEndpoint, e
 				Scheme: "http",
 				Host:   hostname,
 			},
-			Version:                        APIVersion2, //nolint:staticcheck // ignore SA1019 (Version is deprecated) to allow potential consumers to transition.
 			AllowNondistributableArtifacts: ana,
 			TrimHostname:                   true,
 			// used to check if supposed to be secure via InsecureSkipVerify

vendor/github.com/docker/docker/registry/types.go

@@ -5,27 +5,6 @@ import (
 	"github.com/docker/docker/api/types/registry"
 )
 
-// APIVersion is an integral representation of an API version (presently
-// either 1 or 2)
-//
-// Deprecated: v1 registries are deprecated, and endpoints are always v2.
-type APIVersion int
-
-func (av APIVersion) String() string {
-	return apiVersions[av]
-}
-
-// API Version identifiers.
-const (
-	APIVersion1 APIVersion = 1 // Deprecated: v1 registries are deprecated, and endpoints are always v2.
-	APIVersion2 APIVersion = 2 // Deprecated: v1 registries are deprecated, and endpoints are always v2.
-)
-
-var apiVersions = map[APIVersion]string{
-	APIVersion1: "v1",
-	APIVersion2: "v2",
-}
-
 // RepositoryInfo describes a repository
 type RepositoryInfo struct {
 	Name reference.Named
@@ -37,5 +16,7 @@ type RepositoryInfo struct {
 	Official bool
 	// Class represents the class of the repository, such as "plugin"
 	// or "image".
+	//
+	// Deprecated: this field is no longer used, and will be removed in the next release.
 	Class string
 }

vendor/modules.txt

@@ -55,7 +55,7 @@ github.com/docker/distribution/registry/client/transport
 github.com/docker/distribution/registry/storage/cache
 github.com/docker/distribution/registry/storage/cache/memory
 github.com/docker/distribution/uuid
-# github.com/docker/docker v27.0.2-0.20241120142749-e5c2b5e10d68+incompatible
+# github.com/docker/docker v27.0.2-0.20241202115249-87fbd9cd3b37+incompatible
 ## explicit
 github.com/docker/docker/api
 github.com/docker/docker/api/types