Merge pull request #28437 from thaJeztah/deprecate-default-network-inspect

deprecate "top-level" network information in NetworkSettings

docs/deprecated.md

@@ -20,6 +20,26 @@ The following list of features are deprecated in Engine.
 To learn more about Docker Engine's deprecation policy,
 see [Feature Deprecation Policy](https://docs.docker.com/engine/#feature-deprecation-policy).
 
+
+### Top-level network properties in NetworkSettings
+
+**Deprecated In Release: v1.13.0**
+
+**Target For Removal In Release: v1.16**
+
+When inspecting a container, `NetworkSettings` contains top-level information
+about the default ("bridge") network;
+
+`EndpointID`, `Gateway`, `GlobalIPv6Address`, `GlobalIPv6PrefixLen`, `IPAddress`,
+`IPPrefixLen`, `IPv6Gateway`, and `MacAddress`.
+
+These properties are deprecated in favor of per-network properties in
+`NetworkSettings.Networks`. These properties were already "deprecated" in
+docker 1.9, but kept around for backward compatibility.
+
+Refer to [#17538](https://github.com/docker/docker/pull/17538) for further
+information.
+
 ## `filter` param for `/images/json` endpoint
 **Deprecated In Release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**