Networking API and UX documentation

More doc updates will follow

Signed-off-by: Madhu Venugopal <madhu@docker.com>

docs/articles/networking.md

@@ -2,14 +2,17 @@
 +++
 title = "Network configuration"
 description = "Docker networking"
-keywords = ["network, networking, bridge, docker,  documentation"]
+keywords = ["network, networking, bridge, overlay, cluster, multihost, docker, documentation"]
 [menu.main]
 parent= "smn_administrate"
 +++
 <![end-metadata]-->
 
 # Network configuration
 
+> **Note:**
+> This document is outdated and needs a major overhaul.
+
 ## Summary
 
 When Docker starts, it creates a virtual interface named `docker0` on

docs/extend/index.md

@@ -15,6 +15,7 @@ weight = 6
 
 Currently, you can extend Docker by adding a plugin. This section contains the following topics:
 
-* [Understand Docker plugins](/extend/plugins)
-* [Write a volume plugin](/extend/plugins_volume)
-* [Docker plugin API](/extend/plugin_api)
+* [Understand Docker plugins](/extend/plugins.md)
+* [Write a volume plugin](/extend/plugins_volume.md)
+* [Write a network plugin](/extend/plugins_network.md)
+* [Docker plugin API](/extend/plugin_api.md)

docs/extend/plugins.md

@@ -17,8 +17,10 @@ plugins.
 ## Types of plugins
 
 Plugins extend Docker's functionality.  They come in specific types.  For
-example, a [volume plugin](/extend/plugins_volume) might enable Docker
-volumes to persist across multiple Docker hosts.
+example, a [volume plugin](/extend/plugins_volume.md) might enable Docker
+volumes to persist across multiple Docker hosts and a 
+[network plugin](/extend/plugins_network.md) might provide network plumbing
+using a favorite networking technology, such as vxlan overlay, ipvlan, EVPN, etc.
 
 Currently Docker supports volume and network driver plugins. In the future it
 will support additional plugin types.

experimental/plugins_network.md → docs/extend/plugins_network.md

@@ -1,4 +1,4 @@
-# Experimental: Docker network driver plugins
+# Docker network driver plugins
 
 Docker supports network driver plugins via 
 [LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are 
@@ -21,7 +21,9 @@ commands. For example,
 Some network driver plugins are listed in [plugins.md](/docs/extend/plugins.md)
 
 The network thus created is owned by the plugin, so subsequent commands
-referring to that network will also be run through the plugin.
+referring to that network will also be run through the plugin such as,
+
+    docker run --net=mynet busybox top
 
 ## Network driver plugin protocol
 
@@ -36,10 +38,3 @@ Google Groups, or the IRC channel #docker-network.
 
  - [#14083](https://github.com/docker/docker/issues/14083) Feedback on
    experimental networking features
-
-Other pertinent issues:
-
- - [#13977](https://github.com/docker/docker/issues/13977) UI for using networks
- - [#14023](https://github.com/docker/docker/pull/14023) --default-network option
- - [#14051](https://github.com/docker/docker/pull/14051) --publish-service option
- - [#13441](https://github.com/docker/docker/pull/13441) (Deprecated) Networks API & UI

docs/reference/api/docker_remote_api_v1.21.md

@@ -2484,6 +2484,218 @@ Status Codes
 -   **409** - volume is in use and cannot be removed
 -   **500** - server error
 
+## 2.5 Networks
+
+### List networks
+
+`GET /networks`
+
+**Example request**:
+
+  GET /networks HTTP/1.1
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json
+
+```
+  [
+    {
+      "name": "bridge",
+      "id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4",
+      "driver": "bridge"
+    },
+    {
+      "name": "none",
+      "id": "21e34df9b29c74ae45ba312f8e9f83c02433c9a877cfebebcf57be78f69b77c8",
+      "driver": "null"
+    },
+    {
+      "name": "host",
+      "id": "3f43a0873f00310a71cd6a71e2e60c113cf17d1812be2ec22fd519fbac68ec91",
+      "driver": "host"
+    }
+  ]
+```
+
+
+
+Query Parameters:
+
+- **filter** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters: `name=[network-names]` , `id=[network-ids]`
+
+Status Codes:
+
+-   **200** - no error
+-   **500** - server error
+
+### Inspect network
+
+`GET /networks/<network-id>`
+
+**Example request**:
+
+  GET /networks/f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4 HTTP/1.1
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json
+
+```
+  {
+    "name": "bridge",
+    "id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4",
+    "driver": "bridge",
+    "containers": {
+      "931d29e96e63022a3691f55ca18b28600239acf53878451975f77054b05ba559": {
+        "endpoint": "aa79321e2899e6d72fcd46e6a4ad7f81ab9a19c3b06e384ef4ce51fea35827f9",
+        "mac_address": "02:42:ac:11:00:04",
+        "ipv4_address": "172.17.0.4/16"
+      },
+      "961249b4ae6c764b11eed923e8463c102689111fffd933627b2e7e359c7d0f7c": {
+        "endpoint": "4f62c5aea6b9a70512210be7db976bd4ec2cdba47125e4fe514d18c81b1624b1",
+        "mac_address": "02:42:ac:11:00:02",
+        "ipv4_address": "172.17.0.2/16"
+      },
+      "9f6e0fec4449f42a173ed85be96dc2253b6719edd850d8169bc31bdc45db675c": {
+        "endpoint": "352b512a5bccdfc77d16c2c04d04408e718f879a16f9ce3913a4733139e4f98d",
+        "mac_address": "02:42:ac:11:00:03",
+        "ipv4_address": "172.17.0.3/16"
+      }
+    }
+  }
+```
+
+Status Codes:
+
+-   **200** - no error
+-   **404** - network not found
+
+### Create a network
+
+`POST /networks/create`
+
+Create a network
+
+**Example request**:
+
+  POST /networks/create HTTP/1.1
+  Content-Type: application/json
+
+```
+  {
+    "name":"isolated_nw",
+    "driver":"bridge"
+  }
+```
+
+**Example response**:
+
+  HTTP/1.1 201 Created
+  Content-Type: application/json
+
+```
+  {
+    "id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
+    "warning": ""
+  }
+```
+
+Status Codes:
+
+- **201** - no error
+- **404** - driver not found
+- **500** - server error
+
+JSON Parameters:
+
+- **name** - The new network's name. this is a mandatory field
+- **driver** - Name of the network driver to use. Defaults to `bridge` driver
+- **options** - Network specific options to be used by the drivers
+- **check_duplicate** - Requests daemon to check for networks with same name
+
+### Connect a container to a network
+
+`POST /networks/(id)/connect`
+
+Connects a container to a network
+
+**Example request**:
+
+  POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
+  Content-Type: application/json
+
+```
+  {
+    "container":"3613f73ba0e4"
+  }
+```
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+
+Status Codes:
+
+- **201** - no error
+- **404** - network or container is not found
+
+JSON Parameters:
+
+- **container** - container-id/name to be connected to the network
+
+### Disconnect a container from a network
+
+`POST /networks/(id)/disconnect`
+
+Disconnects a container from a network
+
+**Example request**:
+
+  POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
+  Content-Type: application/json
+
+```
+  {
+    "container":"3613f73ba0e4"
+  }
+```
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+
+Status Codes:
+
+- **201** - no error
+- **404** - network or container not found
+
+JSON Parameters:
+
+- **container** - container-id/name to be disconnected from a network
+
+### Remove a network
+
+`DELETE /networks/(id)`
+
+Instruct the driver to remove the network (`id`).
+
+**Example request**:
+
+  DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1
+
+**Example response**:
+
+  HTTP/1.1 204 No Content
+
+Status Codes
+
+-   **204** - no error
+-   **404** - no such network
+-   **500** - server error
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

docs/reference/commandline/network_connect.md

@@ -0,0 +1,30 @@
+<!--[metadata]>
++++
+title = "network connect"
+description = "The network connect command description and usage"
+keywords = ["network, connect"]
+[menu.main]
+parent = "smn_cli"
++++
+<![end-metadata]-->
+
+# network connect
+
+    Usage:  docker network connect [OPTIONS] NETWORK CONTAINER
+
+    Connects a container to a network
+
+      --help=false       Print usage
+
+Connects a running container to a network. This enables instant communication with other containers belonging to the same network. 
+
+```
+  $ docker network create -d overlay multi-host-network
+  $ docker run -d --name=container1 busybox top
+  $ docker network connect multi-host-network container1
+```
+
+the container will be connected to the network that is created and managed by the driver (multi-host overlay driver in the above example) or external network plugins.
+
+Multiple containers can be connected to the same network and the containers in the same network will start to communicate with each other. If the driver/plugin supports multi-host connectivity, then the containers connected to the same multi-host network will be able to communicate seamlessly.
+

docs/reference/commandline/network_create.md

@@ -0,0 +1,32 @@
+<!--[metadata]>
++++
+title = "network create"
+description = "The network create command description and usage"
+keywords = ["network, create"]
+[menu.main]
+parent = "smn_cli"
++++
+<![end-metadata]-->
+
+# network create
+
+    Usage:  docker network create [OPTIONS] NETWORK-NAME
+
+    Creates a new network with a name specified by the user
+
+      -d, --driver=      Driver to manage the Network
+      --help=false       Print usage
+
+Creates a new network that containers can connect to. If the driver supports multi-host networking, the created network will be made available across all the hosts in the cluster. Daemon will do its best to identify network name conflicts. But its the users responsibility to make sure network name is unique across the cluster. You create a network and then configure the container to use it, for example:
+
+```
+  $ docker network create -d overlay multi-host-network
+  $ docker run -itd --net=multi-host-network busybox
+```
+
+the container will be connected to the network that is created and managed by the driver (multi-host overlay driver in the above example) or external network plugins.
+
+Multiple containers can be connected to the same network and the containers in the same network will start to communicate with each other. If the driver/plugin supports multi-host connectivity, then the containers connected to the same multi-host network will be able to communicate seamlessly.
+
+*Note*: UX needs enhancement to accept network options to be passed to the drivers
+

docs/reference/commandline/network_disconnect.md

@@ -0,0 +1,27 @@
+<!--[metadata]>
++++
+title = "network disconnect"
+description = "The network disconnect command description and usage"
+keywords = ["network, disconnect"]
+[menu.main]
+parent = "smn_cli"
++++
+<![end-metadata]-->
+
+# network disconnect
+
+    Usage:  docker network disconnect [OPTIONS] NETWORK CONTAINER
+
+    Disconnects a container from a network
+
+      --help=false       Print usage
+
+Disconnects a running container from a  network.
+
+```
+  $ docker network create -d overlay multi-host-network
+  $ docker run -d --net=multi-host-network --name=container1 busybox top
+  $ docker network disconnect multi-host-network container1
+```
+
+the container will be disconnected from the network.