Add `--filter scope=swarm|local` for `docker network ls`

This fix tries to address the request in 31324 by adding
`--filter scope=swarm|local` for `docker network ls`.

As `docker network ls` has a `SCOPE` column by default,
it is natural to add the support of `--filter scope=swarm|local`.

This fix adds the `scope=swarm|local` support for
`docker network ls --filter`.

Related docs has been updated.

Additional unit test cases have been added.

This fix fixes 31324.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>

api/server/router/network/filter.go

@@ -59,6 +59,11 @@ func filterNetworks(nws []types.NetworkResource, filter filters.Args) ([]types.N
 				continue
 			}
 		}
+		if filter.Include("scope") {
+			if !filter.ExactMatch("scope", nw.Scope) {
+				continue
+			}
+		}
 		displayNet = append(displayNet, nw)
 	}
 

api/server/router/network/filter_test.go

@@ -15,22 +15,32 @@ func TestFilterNetworks(t *testing.T) {
 		{
 			Name:   "host",
 			Driver: "host",
+			Scope:  "local",
 		},
 		{
 			Name:   "bridge",
 			Driver: "bridge",
+			Scope:  "local",
 		},
 		{
 			Name:   "none",
 			Driver: "null",
+			Scope:  "local",
 		},
 		{
 			Name:   "myoverlay",
 			Driver: "overlay",
+			Scope:  "swarm",
 		},
 		{
 			Name:   "mydrivernet",
 			Driver: "mydriver",
+			Scope:  "local",
+		},
+		{
+			Name:   "mykvnet",
+			Driver: "mykvdriver",
+			Scope:  "global",
 		},
 	}
 
@@ -52,6 +62,15 @@ func TestFilterNetworks(t *testing.T) {
 	invalidDriverFilters := filters.NewArgs()
 	invalidDriverFilters.Add("type", "invalid")
 
+	localScopeFilters := filters.NewArgs()
+	localScopeFilters.Add("scope", "local")
+
+	swarmScopeFilters := filters.NewArgs()
+	swarmScopeFilters.Add("scope", "swarm")
+
+	globalScopeFilters := filters.NewArgs()
+	globalScopeFilters.Add("scope", "global")
+
 	testCases := []struct {
 		filter      filters.Args
 		resultCount int
@@ -74,7 +93,7 @@ func TestFilterNetworks(t *testing.T) {
 		},
 		{
 			filter:      customDriverFilters,
-			resultCount: 2,
+			resultCount: 3,
 			err:         "",
 		},
 		{
@@ -87,6 +106,21 @@ func TestFilterNetworks(t *testing.T) {
 			resultCount: 0,
 			err:         "Invalid filter: 'type'='invalid'",
 		},
+		{
+			filter:      localScopeFilters,
+			resultCount: 4,
+			err:         "",
+		},
+		{
+			filter:      swarmScopeFilters,
+			resultCount: 1,
+			err:         "",
+		},
+		{
+			filter:      globalScopeFilters,
+			resultCount: 1,
+			err:         "",
+		},
 	}
 
 	for _, testCase := range testCases {

api/server/router/network/network_routes.go

@@ -27,6 +27,7 @@ var (
 		"name":   true,
 		"id":     true,
 		"label":  true,
+		"scope":  true,
 	}
 )
 

api/swagger.yaml

@@ -6269,6 +6269,7 @@ paths:
             - `id=<network-id>` Matches all or part of a network ID.
             - `label=<key>` or `label=<key>=<value>` of a network label.
             - `name=<network-name>` Matches all or part of a network name.
+            - `scope=["swarm"|"global"|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
             - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks.
           type: "string"
       tags: ["Network"]

docs/api/version-history.md

@@ -13,11 +13,16 @@ keywords: "API, Docker, rcli, REST, documentation"
      will be rejected.
 -->
 
+## v1.29 API changes
+
+[Docker Engine API v1.29](https://docs.docker.com/engine/api/v1.29/) documentation
+
+* `GET /networks/` now supports a `scope` filter to filter networks based on the network mode (`swarm`, `global`, or `local`).
+
 ## v1.28 API changes
 
 [Docker Engine API v1.28](https://docs.docker.com/engine/api/v1.28/) documentation
 
-
 * `POST /containers/create` now includes a `Consistency` field to specify the consistency level for each `Mount`, with possible values `default`, `consistent`, `cached`, or `delegated`.
 * `GET /containers/create` now takes a `DeviceCgroupRules` field in `HostConfig` allowing to set custom device cgroup rules for the created container.
 * Optional query parameter `verbose` for `GET /networks/(id or name)` will now list all services with all the tasks, including the non-local tasks on the given network.

docs/reference/commandline/network_ls.md

@@ -74,6 +74,7 @@ The currently supported filters are:
 * id (network's id)
 * label (`label=<key>` or `label=<key>=<value>`)
 * name (network's name)
+* scope (`swarm|global|local`)
 * type (`custom|builtin`)
 
 #### Driver
@@ -157,6 +158,30 @@ NETWORK ID          NAME                DRIVER       SCOPE
 06e7eef0a170        foobar              bridge       local
 ```
 
+#### Scope
+
+The `scope` filter matches networks based on their scope.
+
+The following example matches networks with the `swarm` scope:
+
+```bash
+$ docker network ls --filter scope=swarm
+NETWORK ID          NAME                DRIVER              SCOPE
+xbtm0v4f1lfh        ingress             overlay             swarm
+ic6r88twuu92        swarmnet            overlay             swarm
+```
+
+The following example matches networks with the `local` scope:
+
+```bash
+$ docker network ls --filter scope=local
+NETWORK ID          NAME                DRIVER              SCOPE
+e85227439ac7        bridge              bridge              local
+0ca0e19443ed        host                host                local
+ca13cc149a36        localnet            bridge              local
+f9e115d2de35        none                null                local
+```
+
 #### Type
 
 The `type` filter supports two values; `builtin` displays predefined networks

man/src/network/ls.md

@@ -35,6 +35,7 @@ The currently supported filters are:
 * id (network's id)
 * label (`label=<key>` or `label=<key>=<value>`)
 * name (network's name)
+* scope (`swarm|global|local`)
 * type (custom|builtin)
 
 #### Driver
@@ -118,6 +119,30 @@ NETWORK ID          NAME                DRIVER
 06e7eef0a170        foobar              bridge
 ```
 
+#### Scope
+
+The `scope` filter matches networks based on their scope.
+
+The following example matches networks with the `swarm` scope:
+
+```bash
+$ docker network ls --filter scope=swarm
+NETWORK ID          NAME                DRIVER              SCOPE
+xbtm0v4f1lfh        ingress             overlay             swarm
+ic6r88twuu92        swarmnet            overlay             swarm
+```
+
+The following example matches networks with the `local` scope:
+
+```bash
+$ docker network ls --filter scope=local
+NETWORK ID          NAME                DRIVER              SCOPE
+e85227439ac7        bridge              bridge              local
+0ca0e19443ed        host                host                local
+ca13cc149a36        localnet            bridge              local
+f9e115d2de35        none                null                local
+```
+
 #### Type
 
 The `type` filter supports two values; `builtin` displays predefined networks