mirror of https://github.com/docker/docs.git
add docs for distributed K/V discovery with secured TLS communication
Signed-off-by: Alexandre Beslic <abronan@docker.com> Closes #1510 and carries Adding abronan's commentary Tweak recommend Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Alexandre Beslic
Mary Anthony
parent
5b28d35d31
commit
fa19c3fd55
|
|
@ -11,218 +11,201 @@ weight=4
|
||||||
|
|
||||||
# Discovery
|
# Discovery
|
||||||
|
|
||||||
Docker Swarm comes with multiple Discovery backends.
|
Docker Swarm comes with multiple discovery backends. You use a hosted discovery service with Docker Swarm. The service maintains a list of IPs in your swarm.
|
||||||
|
This page describes the different types of hosted discovery available to you. These are:
|
||||||
|
|
||||||
## Backends
|
|
||||||
|
|
||||||
You use a hosted discovery service with Docker Swarm. The service
|
## Using a distributed key/value store
|
||||||
maintains a list of IPs in your swarm. There are several available
|
|
||||||
services, such as `etcd`, `consul` and `zookeeper` depending on what
|
|
||||||
is best suited for your environment. You can even use a static
|
|
||||||
file. Docker Hub also provides a hosted discovery service which you
|
|
||||||
can use.
|
|
||||||
|
|
||||||
### Hosted Discovery with Docker Hub
|
The recommended way to do node discovery in Swarm is Docker's libkv project. The libkv project is an abstraction layer over existing distributed key/value stores. As of this writing, the project supports:
|
||||||
|
|
||||||
#####The Hosted Discovery Service is not recommended for production use.
|
* Consul 0.5.1 or higher
|
||||||
#####It's intended to be used for testing/development.
|
* Etcd 2.0 or higher
|
||||||
|
* ZooKeeper 3.4.5 or higher
|
||||||
|
|
||||||
#####See other discovery backends for production use.
|
For details about libkv and a detailed technical overview of the supported backends, refer to the [libkv project](https://github.com/docker/libkv).
|
||||||
|
|
||||||
|
### Using a hosted discovery key store
|
||||||
|
|
||||||
|
1. On each node, start the Swarm agent.
|
||||||
|
|
||||||
|
The node IP address doesn't have to be public as long as the swarm manager can access it.
|
||||||
|
|
||||||
|
**Etcd**:
|
||||||
|
|
||||||
|
swarm join --advertise=<node_ip:2375> etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix>
|
||||||
|
|
||||||
|
**Consul**:
|
||||||
|
|
||||||
|
swarm join --advertise=<node_ip:2375> consul://<consul_addr>/<optional path prefix>
|
||||||
|
|
||||||
|
**ZooKeeper**:
|
||||||
|
|
||||||
|
swarm join --advertise=<node_ip:2375> zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix>
|
||||||
|
|
||||||
|
2. Start the Swarm manager on any machine or your laptop.
|
||||||
|
|
||||||
|
**Etcd**:
|
||||||
|
|
||||||
|
swarm manage -H tcp://<swarm_ip:swarm_port> etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix>
|
||||||
|
|
||||||
|
**Consul**:
|
||||||
|
|
||||||
|
swarm manage -H tcp://<swarm_ip:swarm_port> consul://<consul_addr>/<optional path prefix>
|
||||||
|
|
||||||
|
**ZooKeeper**:
|
||||||
|
|
||||||
|
swarm manage -H tcp://<swarm_ip:swarm_port> zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix>
|
||||||
|
|
||||||
|
4. Use the regular Docker commands.
|
||||||
|
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> info
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> run ...
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> ps
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
||||||
|
...
|
||||||
|
|
||||||
|
5. Try listing the nodes in your cluster.
|
||||||
|
|
||||||
|
**Etcd**:
|
||||||
|
|
||||||
|
swarm list etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix>
|
||||||
|
<node_ip:2375>
|
||||||
|
|
||||||
|
**Consul**:
|
||||||
|
|
||||||
|
swarm list consul://<consul_addr>/<optional path prefix>
|
||||||
|
<node_ip:2375>
|
||||||
|
|
||||||
|
**ZooKeeper**:
|
||||||
|
|
||||||
|
swarm list zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix>
|
||||||
|
<node_ip:2375>
|
||||||
|
|
||||||
|
### Use TLS with distributed key/value discovery
|
||||||
|
|
||||||
|
You can securely talk to the distributed k/v store using TLS. To connect
|
||||||
|
securely to the store, you must generate the certificates for a node when you
|
||||||
|
`join` it to the swarm. You can only use with Consul and Etcd. The following example illustrates this with Consul:
|
||||||
|
|
||||||
|
```
|
||||||
|
swarm join \
|
||||||
|
--advertise=<node_ip:2375> \
|
||||||
|
--discovery-opt kv.cacertfile=/path/to/mycacert.pem \
|
||||||
|
--discovery-opt kv.certfile=/path/to/mycert.pem \
|
||||||
|
--discovery-opt kv.keyfile=/path/to/mykey.pem \
|
||||||
|
consul://<consul_addr>/<optional path prefix>
|
||||||
|
```
|
||||||
|
|
||||||
|
This works the same way for the Swarm `manage` and `list` commands.
|
||||||
|
|
||||||
|
## A static file or list of nodes
|
||||||
|
|
||||||
|
You can use a static file or list of nodes for your discovery backend. The file must be stored on a host that is accessible from the Swarm manager. You can also pass a node list as an option when you start Swarm.
|
||||||
|
|
||||||
|
Both the static file and the `nodes` option support a IP address ranges. To specify a range supply a pattern, for example, `10.0.0.[10:200]` refers to nodes starting from `10.0.0.10` to `10.0.0.200`. For example for the `file` discovery method.
|
||||||
|
|
||||||
|
$ echo "10.0.0.[11:100]:2375" >> /tmp/my_cluster
|
||||||
|
$ echo "10.0.1.[15:20]:2375" >> /tmp/my_cluster
|
||||||
|
$ echo "192.168.1.2:[2:20]375" >> /tmp/my_cluster
|
||||||
|
|
||||||
|
Or with node discovery:
|
||||||
|
|
||||||
|
swarm manage -H <swarm_ip:swarm_port> "nodes://10.0.0.[10:200]:2375,10.0.1.[2:250]:2375"
|
||||||
|
|
||||||
|
### To create a file
|
||||||
|
|
||||||
|
1. Edit the file and add line for each of your nodes.
|
||||||
|
|
||||||
|
echo <node_ip1:2375> >> /opt/my_cluster
|
||||||
|
echo <node_ip2:2375> >> /opt/my_cluster
|
||||||
|
echo <node_ip3:2375> >> /opt/my_cluster
|
||||||
|
|
||||||
|
This example creates a file named `/tmp/my_cluster`. You can use any name you like.
|
||||||
|
|
||||||
|
2. Start the Swarm manager on any machine.
|
||||||
|
|
||||||
|
swarm manage -H tcp://<swarm_ip:swarm_port> file:///tmp/my_cluster
|
||||||
|
|
||||||
|
3. Use the regular Docker commands.
|
||||||
|
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> info
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> run ...
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> ps
|
||||||
|
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
||||||
|
...
|
||||||
|
|
||||||
|
4. List the nodes in your cluster.
|
||||||
|
|
||||||
|
$ swarm list file:///tmp/my_cluster
|
||||||
|
<node_ip1:2375>
|
||||||
|
<node_ip2:2375>
|
||||||
|
<node_ip3:2375>
|
||||||
|
|
||||||
|
### To use a node list
|
||||||
|
|
||||||
|
1. Start the manager on any machine or your laptop.
|
||||||
|
|
||||||
|
swarm manage -H <swarm_ip:swarm_port> nodes://<node_ip1:2375>,<node_ip2:2375>
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
swarm manage -H <swarm_ip:swarm_port> <node_ip1:2375>,<node_ip2:2375>
|
||||||
|
|
||||||
|
2. Use the regular Docker commands.
|
||||||
|
|
||||||
|
docker -H <swarm_ip:swarm_port> info
|
||||||
|
docker -H <swarm_ip:swarm_port> run ...
|
||||||
|
docker -H <swarm_ip:swarm_port> ps
|
||||||
|
docker -H <swarm_ip:swarm_port> logs ...
|
||||||
|
|
||||||
|
3. List the nodes in your cluster.
|
||||||
|
|
||||||
|
$ swarm list file:///tmp/my_cluster
|
||||||
|
<node_ip1:2375>
|
||||||
|
<node_ip2:2375>
|
||||||
|
<node_ip3:2375>
|
||||||
|
|
||||||
|
|
||||||
|
## Docker Hub as a hosted discovery service
|
||||||
|
|
||||||
|
> **Warning**: The Docker Hub Hosted Discovery Service **is not recommended** for production use. It's intended to be used for testing/development. See the discovery backends for production use.
|
||||||
|
|
||||||
This example uses the hosted discovery service on Docker Hub. Using
|
This example uses the hosted discovery service on Docker Hub. Using
|
||||||
Docker Hub's hosted discovery service requires that each node in the
|
Docker Hub's hosted discovery service requires that each node in the
|
||||||
swarm is connected to the internet. To create your swarm:
|
swarm is connected to the public internet. To create your swarm:
|
||||||
|
|
||||||
First we create a cluster.
|
1. Create a cluster.
|
||||||
|
|
||||||
# create a cluster
|
$ swarm create
|
||||||
$ swarm create
|
6856663cdefdec325839a4b7e1de38e8 # <- this is your unique <cluster_id>
|
||||||
6856663cdefdec325839a4b7e1de38e8 # <- this is your unique <cluster_id>
|
|
||||||
|
|
||||||
|
2. Create each node and join them to the cluster.
|
||||||
|
|
||||||
Then we create each node and join them to the cluster.
|
On each of your nodes, start the swarm agent. The <node_ip> doesn't have to be public (eg. 192.168.0.X) but the the swarm manager must be able to access it.
|
||||||
|
|
||||||
# on each of your nodes, start the swarm agent
|
$ swarm join --advertise=<node_ip:2375> token://<cluster_id>
|
||||||
# <node_ip> doesn't have to be public (eg. 192.168.0.X),
|
|
||||||
# as long as the swarm manager can access it.
|
|
||||||
$ swarm join --advertise=<node_ip:2375> token://<cluster_id>
|
|
||||||
|
|
||||||
|
3. Start the Swarm manager.
|
||||||
|
|
||||||
Finally, we start the Swarm manager. This can be on any machine or even
|
This can be on any machine or even your laptop.
|
||||||
your laptop.
|
|
||||||
|
|
||||||
$ swarm manage -H tcp://<swarm_ip:swarm_port> token://<cluster_id>
|
$ swarm manage -H tcp://<swarm_ip:swarm_port> token://<cluster_id>
|
||||||
|
|
||||||
You can then use regular Docker commands to interact with your swarm.
|
4. Use regular Docker commands to interact with your swarm.
|
||||||
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> info
|
docker -H tcp://<swarm_ip:swarm_port> info
|
||||||
docker -H tcp://<swarm_ip:swarm_port> run ...
|
docker -H tcp://<swarm_ip:swarm_port> run ...
|
||||||
docker -H tcp://<swarm_ip:swarm_port> ps
|
docker -H tcp://<swarm_ip:swarm_port> ps
|
||||||
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
||||||
...
|
...
|
||||||
|
|
||||||
|
5. List the nodes in your cluster.
|
||||||
|
|
||||||
You can also list the nodes in your cluster.
|
swarm list token://<cluster_id>
|
||||||
|
<node_ip:2375>
|
||||||
|
|
||||||
swarm list token://<cluster_id>
|
## Contribute a new discovery backend
|
||||||
<node_ip:2375>
|
|
||||||
|
|
||||||
|
|
||||||
### Using a static file describing the cluster
|
|
||||||
|
|
||||||
For each of your nodes, add a line to a file. The node IP address
|
|
||||||
doesn't need to be public as long the Swarm manager can access it.
|
|
||||||
|
|
||||||
echo <node_ip1:2375> >> /tmp/my_cluster
|
|
||||||
echo <node_ip2:2375> >> /tmp/my_cluster
|
|
||||||
echo <node_ip3:2375> >> /tmp/my_cluster
|
|
||||||
|
|
||||||
|
|
||||||
Then start the Swarm manager on any machine.
|
|
||||||
|
|
||||||
swarm manage -H tcp://<swarm_ip:swarm_port> file:///tmp/my_cluster
|
|
||||||
|
|
||||||
|
|
||||||
And then use the regular Docker commands.
|
|
||||||
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> info
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> run ...
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> ps
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
|
||||||
...
|
|
||||||
|
|
||||||
You can list the nodes in your cluster.
|
|
||||||
|
|
||||||
$ swarm list file:///tmp/my_cluster
|
|
||||||
<node_ip1:2375>
|
|
||||||
<node_ip2:2375>
|
|
||||||
<node_ip3:2375>
|
|
||||||
|
|
||||||
|
|
||||||
### Using etcd
|
|
||||||
|
|
||||||
On each of your nodes, start the Swarm agent. The node IP address
|
|
||||||
doesn't have to be public as long as the swarm manager can access it.
|
|
||||||
|
|
||||||
swarm join --advertise=<node_ip:2375> etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix>
|
|
||||||
|
|
||||||
|
|
||||||
Start the manager on any machine or your laptop.
|
|
||||||
|
|
||||||
swarm manage -H tcp://<swarm_ip:swarm_port> etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix>
|
|
||||||
|
|
||||||
|
|
||||||
And then use the regular Docker commands.
|
|
||||||
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> info
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> run ...
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> ps
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
|
||||||
...
|
|
||||||
|
|
||||||
|
|
||||||
You can list the nodes in your cluster.
|
|
||||||
|
|
||||||
swarm list etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix>
|
|
||||||
<node_ip:2375>
|
|
||||||
|
|
||||||
|
|
||||||
### Using consul
|
|
||||||
|
|
||||||
On each of your nodes, start the Swarm agent. The node IP address
|
|
||||||
doesn't need to be public as long as the Swarm manager can access it.
|
|
||||||
|
|
||||||
swarm join --advertise=<node_ip:2375> consul://<consul_addr>/<optional path prefix>
|
|
||||||
|
|
||||||
Start the manager on any machine or your laptop.
|
|
||||||
|
|
||||||
swarm manage -H tcp://<swarm_ip:swarm_port> consul://<consul_addr>/<optional path prefix>
|
|
||||||
|
|
||||||
|
|
||||||
And then use the regular Docker commands.
|
|
||||||
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> info
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> run ...
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> ps
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
|
||||||
...
|
|
||||||
|
|
||||||
You can list the nodes in your cluster.
|
|
||||||
|
|
||||||
swarm list consul://<consul_addr>/<optional path prefix>
|
|
||||||
<node_ip:2375>
|
|
||||||
|
|
||||||
|
|
||||||
### Using zookeeper
|
|
||||||
|
|
||||||
On each of your nodes, start the Swarm agent. The node IP doesn't have
|
|
||||||
to be public as long as the swarm manager can access it.
|
|
||||||
|
|
||||||
swarm join --advertise=<node_ip:2375> zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix>
|
|
||||||
|
|
||||||
|
|
||||||
Start the manager on any machine or your laptop.
|
|
||||||
|
|
||||||
swarm manage -H tcp://<swarm_ip:swarm_port> zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix>
|
|
||||||
|
|
||||||
You can then use the regular Docker commands.
|
|
||||||
|
|
||||||
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> info
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> run ...
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> ps
|
|
||||||
docker -H tcp://<swarm_ip:swarm_port> logs ...
|
|
||||||
...
|
|
||||||
|
|
||||||
|
|
||||||
You can list the nodes in the cluster.
|
|
||||||
|
|
||||||
swarm list zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix>
|
|
||||||
<node_ip:2375>
|
|
||||||
|
|
||||||
|
|
||||||
### Using a static list of IP addresses
|
|
||||||
|
|
||||||
Start the manager on any machine or your laptop
|
|
||||||
|
|
||||||
swarm manage -H <swarm_ip:swarm_port> nodes://<node_ip1:2375>,<node_ip2:2375>
|
|
||||||
|
|
||||||
Or
|
|
||||||
|
|
||||||
swarm manage -H <swarm_ip:swarm_port> <node_ip1:2375>,<node_ip2:2375>
|
|
||||||
|
|
||||||
|
|
||||||
Then use the regular Docker commands.
|
|
||||||
|
|
||||||
docker -H <swarm_ip:swarm_port> info
|
|
||||||
docker -H <swarm_ip:swarm_port> run ...
|
|
||||||
docker -H <swarm_ip:swarm_port> ps
|
|
||||||
docker -H <swarm_ip:swarm_port> logs ...
|
|
||||||
|
|
||||||
|
|
||||||
### Range pattern for IP addresses
|
|
||||||
|
|
||||||
The `file` and `nodes` discoveries support a range pattern to specify IP
|
|
||||||
addresses, i.e., `10.0.0.[10:200]` will be a list of nodes starting from
|
|
||||||
`10.0.0.10` to `10.0.0.200`.
|
|
||||||
|
|
||||||
For example for the `file` discovery method.
|
|
||||||
|
|
||||||
$ echo "10.0.0.[11:100]:2375" >> /tmp/my_cluster
|
|
||||||
$ echo "10.0.1.[15:20]:2375" >> /tmp/my_cluster
|
|
||||||
$ echo "192.168.1.2:[2:20]375" >> /tmp/my_cluster
|
|
||||||
|
|
||||||
Then start the manager.
|
|
||||||
|
|
||||||
swarm manage -H tcp://<swarm_ip:swarm_port> file:///tmp/my_cluster
|
|
||||||
|
|
||||||
|
|
||||||
And for the `nodes` discovery method.
|
|
||||||
|
|
||||||
swarm manage -H <swarm_ip:swarm_port> "nodes://10.0.0.[10:200]:2375,10.0.1.[2:250]:2375"
|
|
||||||
|
|
||||||
|
|
||||||
## Contributing a new discovery backend
|
|
||||||
|
|
||||||
You can contribute a new discovery backend to Swarm. For information on how to
|
You can contribute a new discovery backend to Swarm. For information on how to
|
||||||
do this, see <a
|
do this, see <a
|
||||||
|
|
@ -231,7 +214,7 @@ discovery README in the Docker Swarm repository</a>.
|
||||||
|
|
||||||
## Docker Swarm documentation index
|
## Docker Swarm documentation index
|
||||||
|
|
||||||
- [User guide]()
|
- [Overview](index.md)
|
||||||
- [Scheduler strategies](scheduler/strategy.md)
|
- [Scheduler strategies](scheduler/strategy.md)
|
||||||
- [Scheduler filters](scheduler/filter.md)
|
- [Scheduler filters](scheduler/filter.md)
|
||||||
- [Swarm API](api/swarm-api.md)
|
- [Swarm API](api/swarm-api.md)
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue