clearlinux/docker
2
0
Fork 0
mirror of https://github.com/clearlinux/docker.git synced 2026-09-08 15:01:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Networking API and UX documentation

Browse Source 
More doc updates will follow

Signed-off-by: Madhu Venugopal <madhu@docker.com>
This commit is contained in:
Madhu Venugopal
2015-10-07 03:54:27 -07:00
parent 22a9ba090e
commit dd28ded711
21 changed files with 994 additions and 901 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/api/docker_remote_api_v1.21.md
+212
View File
@@ -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
+30
View File
@@ -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
+32
View File
@@ -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
+27
View File
@@ -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.
docs/reference/commandline/network_inspect.md
+49
View File
@@ -0,0 +1,49 @@
<!--[metadata]>
+++
title = "network inspect"
description = "The network inspect command description and usage"
keywords = ["network, inspect"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network inspect
Usage: docker network inspect [OPTIONS] NETWORK
Displays detailed information on a network
--help=false Print usage
Returns information about a network. By default, this command renders all results
in a JSON object.
Example output:
```
$ sudo docker run -itd --name=container1 busybox
f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27
$ sudo docker run -itd --name=container2 busybox
bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727
$ sudo docker network inspect bridge
{
"name": "bridge",
"id": "7fca4eb8c647e57e9d46c32714271e0c3f8bf8d17d346629e2820547b2d90039",
"driver": "bridge",
"containers": {
"bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727": {
"endpoint": "e0ac95934f803d7e36384a2029b8d1eeb56cb88727aa2e8b7edfeebaa6dfd758",
"mac_address": "02:42:ac:11:00:03",
"ipv4_address": "172.17.0.3/16"
},
"f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27": {
"endpoint": "31de280881d2a774345bbfb1594159ade4ae4024ebfb1320cb74a30225f6a8ae",
"mac_address": "02:42:ac:11:00:02",
"ipv4_address": "172.17.0.2/16"
}
}
}
```
docs/reference/commandline/network_ls.md
+32
View File
@@ -0,0 +1,32 @@
<!--[metadata]>
+++
title = "network ls"
description = "The network ls command description and usage"
keywords = ["network, list"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# docker network ls
Usage: docker network ls [OPTIONS]
Lists all the networks created by the user
--help=false Print usage
-l, --latest=false Show the latest network created
-n=-1 Show n last created networks
--no-trunc=false Do not truncate the output
-q, --quiet=false Only display numeric IDs
Lists all the networks Docker knows about. This include the networks that spans across multiple hosts in a cluster.
Example output:
```
$ sudo docker network ls
NETWORK ID NAME DRIVER
7fca4eb8c647 bridge bridge
9f904ee27bf5 none null
cf03ee007fb4 host host
```
docs/reference/commandline/network_rm.md
+23
View File
@@ -0,0 +1,23 @@
<!--[metadata]>
+++
title = "network rm"
description = "the network rm command description and usage"
keywords = ["network, rm"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network rm
Usage: docker network rm [OPTIONS] NETWORK
Deletes a network
--help=false Print usage
Removes a network. You cannot remove a network that is in use by 1 or more containers.
```
$ docker network rm my-network
```
docs/reference/glossary.md
+12 -1
View File
@@ -132,6 +132,12 @@ namespaces, cgroups, capabilities, and filesystem access controls. It allows
you to manage the lifecycle of the container performing additional operations
after the container is created.
## libnetwork
libnetwork provides a native Go implementation for creating and managing container
network namespaces and other network resources. It manage the networking lifecycle
of the container performing additional operations after the container is created.
## link
links provide an interface to connect Docker containers running on the same host
@@ -149,7 +155,12 @@ installs Docker on them, then configures the Docker client to talk to them.
*Also known as : docker-machine*
## overlay
## overlay network driver
Overlay network driver provides out of the box multi-host network connectivity
for docker containers in a cluster.
## overlay storage driver
OverlayFS is a [filesystem](#filesystem) service for Linux which implements a
[union mount](http://en.wikipedia.org/wiki/Union_mount) for other file systems.
docs/reference/run.md
+33 -11
View File
@@ -245,11 +245,12 @@ of the containers.
## Network settings
--dns=[] : Set custom dns servers for the container
--net="bridge" : Set the Network mode for the container
--net="bridge" : Connects a container to a network
'bridge': creates a new network stack for the container on the docker bridge
'none': no networking for this container
'container:<name|id>': reuses another container network stack
'host': use the host network stack inside the container
'NETWORK': connects the container to user-created network using `docker network create` command
--add-host="" : Add a line to /etc/hosts (host:IP)
--mac-address="" : Sets the container's Ethernet device's MAC address
@@ -269,12 +270,12 @@ By default, the MAC address is generated using the IP address allocated to the
container. You can set the container's MAC address explicitly by providing a
MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`).
Supported networking modes are:
Supported networks :
<table>
<thead>
<tr>
<th class="no-wrap">Mode</th>
<th class="no-wrap">Network</th>
<th>Description</th>
</tr>
</thead>
@@ -304,19 +305,25 @@ Supported networking modes are:
its *name* or *id*.
</td>
</tr>
<tr>
<td class="no-wrap"><strong>NETWORK</strong></td>
<td>
Connects the container to a user created network (using `docker network create` command)
</td>
</tr>
</tbody>
</table>
#### Mode: none
#### Network: none
With the networking mode set to `none` a container will not have a
With the network is `none` a container will not have
access to any external routes. The container will still have a
`loopback` interface enabled in the container but it does not have any
routes to external traffic.
#### Mode: bridge
#### Network: bridge
With the networking mode set to `bridge` a container will use docker's
With the network set to `bridge` a container will use docker's
default networking setup. A bridge is setup on the host, commonly named
`docker0`, and a pair of `veth` interfaces will be created for the
container. One side of the `veth` pair will remain on the host attached
@@ -325,9 +332,9 @@ container's namespaces in addition to the `loopback` interface. An IP
address will be allocated for containers on the bridge's network and
traffic will be routed though this bridge to the container.
#### Mode: host
#### Network: host
With the networking mode set to `host` a container will share the host's
With the network set to `host` a container will share the host's
network stack and all interfaces from the host will be available to the
container. The container's hostname will match the hostname on the host
system. Note that `--add-host` `--hostname` `--dns` `--dns-search`
@@ -343,9 +350,9 @@ or a High Performance Web Server.
> **Note**: `--net="host"` gives the container full access to local system
> services such as D-bus and is therefore considered insecure.
#### Mode: container
#### Network: container
With the networking mode set to `container` a container will share the
With the network set to `container` a container will share the
network stack of another container. The other container's name must be
provided in the format of `--net container:<name|id>`. Note that `--add-host`
`--hostname` `--dns` `--dns-search` `--dns-opt` and `--mac-address` are
@@ -360,6 +367,21 @@ running the `redis-cli` command and connecting to the Redis server over the
$ # use the redis container's network stack to access localhost
$ docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1
#### Network: User-Created NETWORK
In addition to all the above special networks, user can create a network using
their favorite network driver or external plugin. The driver used to create the
network takes care of all the network plumbing requirements for the container
connected to that network.
Example creating a network using the inbuilt overlay network driver and running
a container in the created network
```
$ docker network create -d overlay multi-host-network
$ docker run --net=multi-host-network -itd --name=container3 busybox
```
### Managing /etc/hosts
Your container will have lines in `/etc/hosts` which define the hostname of the