Skip to content

Commit 2861734

Browse files
vvolandvvoland
authored
Merge pull request #47892 from thaJeztah/26.1_backport_api_docs_network_config_only
[26.1 backport] api: networking: document Scope, ConfigOnly, ConfigFrom, Peers
2 parents 9c95aea + 0fd5efe commit 2861734

File tree

7 files changed

+939
-387
lines changed

7 files changed

+939
-387
lines changed

‎api/swagger.yaml

Lines changed: 154 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -2179,79 +2179,137 @@ definitions:
21792179
type: "object"
21802180
properties:
21812181
Name:
2182+
description: |
2183+
Name of the network.
21822184
type: "string"
2185+
example: "my_network"
21832186
Id:
2187+
description: |
2188+
ID that uniquely identifies a network on a single machine.
21842189
type: "string"
2190+
example: "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99"
21852191
Created:
2192+
description: |
2193+
Date and time at which the network was created in
2194+
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.
21862195
type: "string"
21872196
format: "dateTime"
2197+
example: "2016-10-19T04:33:30.360899459Z"
21882198
Scope:
2199+
description: |
2200+
The level at which the network exists (e.g. `swarm` for cluster-wide
2201+
or `local` for machine level)
21892202
type: "string"
2203+
example: "local"
21902204
Driver:
2205+
description: |
2206+
The name of the driver used to create the network (e.g. `bridge`,
2207+
`overlay`).
21912208
type: "string"
2209+
example: "overlay"
21922210
EnableIPv6:
2211+
description: |
2212+
Whether the network was created with IPv6 enabled.
21932213
type: "boolean"
2214+
example: false
21942215
IPAM:
21952216
$ref: "#/definitions/IPAM"
21962217
Internal:
2218+
description: |
2219+
Whether the network is created to only allow internal networking
2220+
connectivity.
21972221
type: "boolean"
2222+
default: false
2223+
example: false
21982224
Attachable:
2225+
description: |
2226+
Wheter a global / swarm scope network is manually attachable by regular
2227+
containers from workers in swarm mode.
21992228
type: "boolean"
2229+
default: false
2230+
example: false
22002231
Ingress:
2232+
description: |
2233+
Whether the network is providing the routing-mesh for the swarm cluster.
22012234
type: "boolean"
2235+
default: false
2236+
example: false
2237+
ConfigFrom:
2238+
$ref: "#/definitions/ConfigReference"
2239+
ConfigOnly:
2240+
description: |
2241+
Whether the network is a config-only network. Config-only networks are
2242+
placeholder networks for network configurations to be used by other
2243+
networks. Config-only networks cannot be used directly to run containers
2244+
or services.
2245+
type: "boolean"
2246+
default: false
22022247
Containers:
2248+
description: |
2249+
Contains endpoints attached to the network.
22032250
type: "object"
22042251
additionalProperties:
22052252
$ref: "#/definitions/NetworkContainer"
2253+
example:
2254+
19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c:
2255+
Name: "test"
2256+
EndpointID: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a"
2257+
MacAddress: "02:42:ac:13:00:02"
2258+
IPv4Address: "172.19.0.2/16"
2259+
IPv6Address: ""
22062260
Options:
2261+
description: |
2262+
Network-specific options uses when creating the network.
22072263
type: "object"
22082264
additionalProperties:
22092265
type: "string"
2266+
example:
2267+
com.docker.network.bridge.default_bridge: "true"
2268+
com.docker.network.bridge.enable_icc: "true"
2269+
com.docker.network.bridge.enable_ip_masquerade: "true"
2270+
com.docker.network.bridge.host_binding_ipv4: "0.0.0.0"
2271+
com.docker.network.bridge.name: "docker0"
2272+
com.docker.network.driver.mtu: "1500"
22102273
Labels:
2274+
description: "User-defined key/value metadata."
22112275
type: "object"
22122276
additionalProperties:
22132277
type: "string"
2214-
example:
2215-
Name: "net01"
2216-
Id: "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99"
2217-
Created: "2016-10-19T04:33:30.360899459Z"
2218-
Scope: "local"
2219-
Driver: "bridge"
2220-
EnableIPv6: false
2221-
IPAM:
2222-
Driver: "default"
2223-
Config:
2224-
- Subnet: "172.19.0.0/16"
2225-
Gateway: "172.19.0.1"
2226-
Options:
2227-
foo: "bar"
2228-
Internal: false
2229-
Attachable: false
2230-
Ingress: false
2231-
Containers:
2232-
19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c:
2233-
Name: "test"
2234-
EndpointID: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a"
2235-
MacAddress: "02:42:ac:13:00:02"
2236-
IPv4Address: "172.19.0.2/16"
2237-
IPv6Address: ""
2238-
Options:
2239-
com.docker.network.bridge.default_bridge: "true"
2240-
com.docker.network.bridge.enable_icc: "true"
2241-
com.docker.network.bridge.enable_ip_masquerade: "true"
2242-
com.docker.network.bridge.host_binding_ipv4: "0.0.0.0"
2243-
com.docker.network.bridge.name: "docker0"
2244-
com.docker.network.driver.mtu: "1500"
2245-
Labels:
2246-
com.example.some-label: "some-value"
2247-
com.example.some-other-label: "some-other-value"
2278+
example:
2279+
com.example.some-label: "some-value"
2280+
com.example.some-other-label: "some-other-value"
2281+
Peers:
2282+
description: |
2283+
List of peer nodes for an overlay network. This field is only present
2284+
for overlay networks, and omitted for other network types.
2285+
type: "array"
2286+
items:
2287+
$ref: "#/definitions/PeerInfo"
2288+
x-nullable: true
2289+
# TODO: Add Services (only present when "verbose" is set).
2290+
2291+
ConfigReference:
2292+
description: |
2293+
The config-only network source to provide the configuration for
2294+
this network.
2295+
type: "object"
2296+
properties:
2297+
Network:
2298+
description: |
2299+
The name of the config-only network that provides the network's
2300+
configuration. The specified network must be an existing config-only
2301+
network. Only network names are allowed, not network IDs.
2302+
type: "string"
2303+
example: "config_only_network_01"
2304+
22482305
IPAM:
22492306
type: "object"
22502307
properties:
22512308
Driver:
22522309
description: "Name of the IPAM driver to use."
22532310
type: "string"
22542311
default: "default"
2312+
example: "default"
22552313
Config:
22562314
description: |
22572315
List of IPAM configuration options, specified as a map:
@@ -2267,16 +2325,21 @@ definitions:
22672325
type: "object"
22682326
additionalProperties:
22692327
type: "string"
2328+
example:
2329+
foo: "bar"
22702330

22712331
IPAMConfig:
22722332
type: "object"
22732333
properties:
22742334
Subnet:
22752335
type: "string"
2336+
example: "172.20.0.0/16"
22762337
IPRange:
22772338
type: "string"
2339+
example: "172.20.10.0/24"
22782340
Gateway:
22792341
type: "string"
2342+
example: "172.20.10.11"
22802343
AuxiliaryAddresses:
22812344
type: "object"
22822345
additionalProperties:
@@ -2287,14 +2350,35 @@ definitions:
22872350
properties:
22882351
Name:
22892352
type: "string"
2353+
example: "container_1"
22902354
EndpointID:
22912355
type: "string"
2356+
example: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a"
22922357
MacAddress:
22932358
type: "string"
2359+
example: "02:42:ac:13:00:02"
22942360
IPv4Address:
22952361
type: "string"
2362+
example: "172.19.0.2/16"
22962363
IPv6Address:
22972364
type: "string"
2365+
example: ""
2366+
2367+
PeerInfo:
2368+
description: |
2369+
PeerInfo represents one peer of an overlay network.
2370+
type: "object"
2371+
properties:
2372+
Name:
2373+
description:
2374+
ID of the peer-node in the Swarm cluster.
2375+
type: "string"
2376+
example: "6869d7c1732b"
2377+
IP:
2378+
description:
2379+
IP-address of the peer-node in the Swarm cluster.
2380+
type: "string"
2381+
example: "10.133.77.91"
22982382

22992383
BuildInfo:
23002384
type: "object"
@@ -10104,14 +10188,22 @@ paths:
1010410188
Name:
1010510189
description: "The network's name."
1010610190
type: "string"
10191+
example: "my_network"
1010710192
CheckDuplicate:
1010810193
description: |
1010910194
Deprecated: CheckDuplicate is now always enabled.
1011010195
type: "boolean"
10196+
example: true
1011110197
Driver:
1011210198
description: "Name of the network driver plugin to use."
1011310199
type: "string"
1011410200
default: "bridge"
10201+
example: "bridge"
10202+
Scope:
10203+
description: |
10204+
The level at which the network exists (e.g. `swarm` for cluster-wide
10205+
or `local` for machine level).
10206+
type: "string"
1011510207
Internal:
1011610208
description: "Restrict external access to the network."
1011710209
type: "boolean"
@@ -10120,55 +10212,55 @@ paths:
1012010212
Globally scoped network is manually attachable by regular
1012110213
containers from workers in swarm mode.
1012210214
type: "boolean"
10215+
example: true
1012310216
Ingress:
1012410217
description: |
1012510218
Ingress network is the network which provides the routing-mesh
1012610219
in swarm mode.
1012710220
type: "boolean"
10221+
example: false
10222+
ConfigOnly:
10223+
description: |
10224+
Creates a config-only network. Config-only networks are placeholder
10225+
networks for network configurations to be used by other networks.
10226+
Config-only networks cannot be used directly to run containers
10227+
or services.
10228+
type: "boolean"
10229+
default: false
10230+
example: false
10231+
ConfigFrom:
10232+
description: |
10233+
Specifies the source which will provide the configuration for
10234+
this network. The specified network must be an existing
10235+
config-only network; see ConfigOnly.
10236+
$ref: "#/definitions/ConfigReference"
1012810237
IPAM:
1012910238
description: "Optional custom IP scheme for the network."
1013010239
$ref: "#/definitions/IPAM"
1013110240
EnableIPv6:
1013210241
description: "Enable IPv6 on the network."
1013310242
type: "boolean"
10243+
example: true
1013410244
Options:
1013510245
description: "Network specific options to be used by the drivers."
1013610246
type: "object"
1013710247
additionalProperties:
1013810248
type: "string"
10249+
example:
10250+
com.docker.network.bridge.default_bridge: "true"
10251+
com.docker.network.bridge.enable_icc: "true"
10252+
com.docker.network.bridge.enable_ip_masquerade: "true"
10253+
com.docker.network.bridge.host_binding_ipv4: "0.0.0.0"
10254+
com.docker.network.bridge.name: "docker0"
10255+
com.docker.network.driver.mtu: "1500"
1013910256
Labels:
1014010257
description: "User-defined key/value metadata."
1014110258
type: "object"
1014210259
additionalProperties:
1014310260
type: "string"
10144-
example:
10145-
Name: "isolated_nw"
10146-
CheckDuplicate: false
10147-
Driver: "bridge"
10148-
EnableIPv6: true
10149-
IPAM:
10150-
Driver: "default"
10151-
Config:
10152-
- Subnet: "172.20.0.0/16"
10153-
IPRange: "172.20.10.0/24"
10154-
Gateway: "172.20.10.11"
10155-
- Subnet: "2001:db8:abcd::/64"
10156-
Gateway: "2001:db8:abcd::1011"
10157-
Options:
10158-
foo: "bar"
10159-
Internal: true
10160-
Attachable: false
10161-
Ingress: false
10162-
Options:
10163-
com.docker.network.bridge.default_bridge: "true"
10164-
com.docker.network.bridge.enable_icc: "true"
10165-
com.docker.network.bridge.enable_ip_masquerade: "true"
10166-
com.docker.network.bridge.host_binding_ipv4: "0.0.0.0"
10167-
com.docker.network.bridge.name: "docker0"
10168-
com.docker.network.driver.mtu: "1500"
10169-
Labels:
10170-
com.example.some-label: "some-value"
10171-
com.example.some-other-label: "some-other-value"
10261+
example:
10262+
com.example.some-label: "some-value"
10263+
com.example.some-other-label: "some-other-value"
1017210264
tags: ["Network"]
1017310265

1017410266
/networks/{id}/connect:

‎api/types/types.go

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -457,24 +457,24 @@ type EndpointResource struct {
457457
type NetworkCreate struct {
458458
// Deprecated: CheckDuplicate is deprecated since API v1.44, but it defaults to true when sent by the client
459459
// package to older daemons.
460-
CheckDuplicate bool `json:",omitempty"`
461-
Driver string
462-
Scope string
463-
EnableIPv6 bool
464-
IPAM *network.IPAM
465-
Internal bool
466-
Attachable bool
467-
Ingress bool
468-
ConfigOnly bool
469-
ConfigFrom *network.ConfigReference
470-
Options map[string]string
471-
Labels map[string]string
460+
CheckDuplicate bool `json:",omitempty"`
461+
Driver string // Driver is the driver-name used to create the network (e.g. `bridge`, `overlay`)
462+
Scope string // Scope describes the level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).
463+
EnableIPv6 bool // EnableIPv6 represents whether to enable IPv6.
464+
IPAM *network.IPAM // IPAM is the network's IP Address Management.
465+
Internal bool // Internal represents if the network is used internal only.
466+
Attachable bool // Attachable represents if the global scope is manually attachable by regular containers from workers in swarm mode.
467+
Ingress bool // Ingress indicates the network is providing the routing-mesh for the swarm cluster.
468+
ConfigOnly bool // ConfigOnly creates a config-only network. Config-only networks are place-holder networks for network configurations to be used by other networks. ConfigOnly networks cannot be used directly to run containers or services.
469+
ConfigFrom *network.ConfigReference // ConfigFrom specifies the source which will provide the configuration for this network. The specified network must be a config-only network; see [NetworkCreate.ConfigOnly].
470+
Options map[string]string // Options specifies the network-specific options to use for when creating the network.
471+
Labels map[string]string // Labels holds metadata specific to the network being created.
472472
}
473473

474474
// NetworkCreateRequest is the request message sent to the server for network create call.
475475
type NetworkCreateRequest struct {
476476
NetworkCreate
477-
Name string
477+
Name string // Name is the requested name of the network.
478478
}
479479

480480
// NetworkCreateResponse is the response message sent by the server for network create call

0 commit comments

Comments
 (0)