diff --git a/api/server/router/network/filter.go b/api/server/router/network/filter.go index 4a92fd19c8..afe4e235e3 100644 --- a/api/server/router/network/filter.go +++ b/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) } diff --git a/api/server/router/network/filter_test.go b/api/server/router/network/filter_test.go index 222339947b..af3e949546 100644 --- a/api/server/router/network/filter_test.go +++ b/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 { diff --git a/api/server/router/network/network_routes.go b/api/server/router/network/network_routes.go index c33191646f..1d8f31a09a 100644 --- a/api/server/router/network/network_routes.go +++ b/api/server/router/network/network_routes.go @@ -27,6 +27,7 @@ var ( "name": true, "id": true, "label": true, + "scope": true, } ) diff --git a/api/swagger.yaml b/api/swagger.yaml index bf76d8b50c..343f015cd4 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -6269,6 +6269,7 @@ paths: - `id=` Matches all or part of a network ID. - `label=` or `label==` of a network label. - `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"] diff --git a/docs/api/version-history.md b/docs/api/version-history.md index ff65bb5a55..97ea050a62 100644 --- a/docs/api/version-history.md +++ b/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. diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md index 39dcd051d9..8bb8a2c48a 100644 --- a/docs/reference/commandline/network_ls.md +++ b/docs/reference/commandline/network_ls.md @@ -74,6 +74,7 @@ The currently supported filters are: * id (network's id) * label (`label=` or `label==`) * 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 diff --git a/man/src/network/ls.md b/man/src/network/ls.md index c5182e87e1..417344951a 100644 --- a/man/src/network/ls.md +++ b/man/src/network/ls.md @@ -35,6 +35,7 @@ The currently supported filters are: * id (network's id) * label (`label=` or `label==`) * 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