Merge pull request #47015 from thaJeztah/api_fields_deprecation

api: Deprecate outdated fields in NetworkSettingsBase

api/swagger.yaml

@@ -1398,7 +1398,8 @@ definitions:
     type: "object"
     properties:
       Bridge:
-        description: Name of the network's bridge (for example, `docker0`).
+        description: |
+          Name of the default bridge interface when dockerd's --bridge flag is set.
         type: "string"
         example: "docker0"
       SandboxID:
@@ -1408,34 +1409,40 @@ definitions:
       HairpinMode:
         description: |
           Indicates if hairpin NAT should be enabled on the virtual interface.
+
+          Deprecated: This field is never set and will be removed in a future release.
         type: "boolean"
         example: false
       LinkLocalIPv6Address:
-        description: IPv6 unicast address using the link-local prefix.
+        description: |
+          IPv6 unicast address using the link-local prefix.
+
+          Deprecated: This field is never set and will be removed in a future release.
         type: "string"
-        example: "fe80::42:acff:fe11:1"
+        example: ""
       LinkLocalIPv6PrefixLen:
-        description: Prefix length of the IPv6 unicast address.
+        description: |
+          Prefix length of the IPv6 unicast address.
+
+          Deprecated: This field is never set and will be removed in a future release.
         type: "integer"
-        example: "64"
+        example: ""
       Ports:
         $ref: "#/definitions/PortMap"
       SandboxKey:
-        description: SandboxKey identifies the sandbox
+        description: SandboxKey is the full path of the netns handle
         type: "string"
         example: "/var/run/docker/netns/8ab54b426c38"
 
-      # TODO is SecondaryIPAddresses actually used?
       SecondaryIPAddresses:
-        description: ""
+        description: "Deprecated: This field is never set and will be removed in a future release."
         type: "array"
         items:
           $ref: "#/definitions/Address"
         x-nullable: true
 
-      # TODO is SecondaryIPv6Addresses actually used?
       SecondaryIPv6Addresses:
-        description: ""
+        description: "Deprecated: This field is never set and will be removed in a future release."
         type: "array"
         items:
           $ref: "#/definitions/Address"

api/types/types.go

@@ -339,17 +339,27 @@ type SummaryNetworkSettings struct {
 	Networks map[string]*network.EndpointSettings
 }
 
-// NetworkSettingsBase holds basic information about networks
+// NetworkSettingsBase holds networking state for a container when inspecting it.
 type NetworkSettingsBase struct {
-	Bridge                 string      // Bridge is the Bridge name the network uses(e.g. `docker0`)
-	SandboxID              string      // SandboxID uniquely represents a container's network stack
-	HairpinMode            bool        // HairpinMode specifies if hairpin NAT should be enabled on the virtual interface
-	LinkLocalIPv6Address   string      // LinkLocalIPv6Address is an IPv6 unicast address using the link-local prefix
-	LinkLocalIPv6PrefixLen int         // LinkLocalIPv6PrefixLen is the prefix length of an IPv6 unicast address
-	Ports                  nat.PortMap // Ports is a collection of PortBinding indexed by Port
-	SandboxKey             string      // SandboxKey identifies the sandbox
-	SecondaryIPAddresses   []network.Address
-	SecondaryIPv6Addresses []network.Address
+	Bridge     string      // Bridge contains the name of the default bridge interface iff it was set through the daemon --bridge flag.
+	SandboxID  string      // SandboxID uniquely represents a container's network stack
+	SandboxKey string      // SandboxKey identifies the sandbox
+	Ports      nat.PortMap // Ports is a collection of PortBinding indexed by Port
+
+	// HairpinMode specifies if hairpin NAT should be enabled on the virtual interface
+	//
+	// Deprecated: This field is never set and will be removed in a future release.
+	HairpinMode bool
+	// LinkLocalIPv6Address is an IPv6 unicast address using the link-local prefix
+	//
+	// Deprecated: This field is never set and will be removed in a future release.
+	LinkLocalIPv6Address string
+	// LinkLocalIPv6PrefixLen is the prefix length of an IPv6 unicast address
+	//
+	// Deprecated: This field is never set and will be removed in a future release.
+	LinkLocalIPv6PrefixLen int
+	SecondaryIPAddresses   []network.Address // Deprecated: This field is never set and will be removed in a future release.
+	SecondaryIPv6Addresses []network.Address // Deprecated: This field is never set and will be removed in a future release.
 }
 
 // DefaultNetworkSettings holds network information

docs/api/version-history.md

@@ -75,6 +75,10 @@ keywords: "API, Docker, rcli, REST, documentation"
   Starting with that API version, this specific value will  be removed from the `Aliases` field
   such that this field will reflect exactly the values originally submitted to the
   `POST /containers/create` endpoint. The newly introduced `DNSNames` should now be used instead.
+* The fields `HairpinMode`, `LinkLocalIPv6Address`, `LinkLocalIPv6PrefixLen`, `SecondaryIPAddresses`,
+  `SecondaryIPv6Addresses` available in `NetworkSettings` when calling `GET /containers/{id}/json` are
+  deprecated and will be removed in a future release. You should instead look for the default network in
+  `NetworkSettings.Networks`.
 
 ## v1.43 API changes