--- page_title: Docker Swarm discovery page_description: Swarm discovery page_keywords: docker, swarm, clustering, discovery --- # Discovery Docker Swarm comes with multiple Discovery backends. ## Backends You use a hosted discovery service with Docker Swarm. The service 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 This example uses the hosted discovery service on Docker Hub. Using Docker Hub's hosted discovery service requires that each node in the swarm is connected to the internet. To create your swarm: First we create a cluster. ```bash # create a cluster $ swarm create 6856663cdefdec325839a4b7e1de38e8 # <- this is your unique ``` Then we create each node and join them to the cluster. ```bash # on each of your nodes, start the swarm agent # doesn't have to be public (eg. 192.168.0.X), # as long as the swarm manager can access it. $ swarm join --advertise= token:// ``` Finally, we start the Swarm manager. This can be on any machine or even your laptop. ```bash $ swarm manage -H tcp:// token:// ``` You can then use regular Docker commands to interact with your swarm. ```bash docker -H tcp:// info docker -H tcp:// run ... docker -H tcp:// ps docker -H tcp:// logs ... ... ``` You can also list the nodes in your cluster. ```bash swarm list token:// ``` ### 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. ```bash echo >> /tmp/my_cluster echo >> /tmp/my_cluster echo >> /tmp/my_cluster ``` Then start the Swarm manager on any machine. ```bash swarm manage -H tcp:// file:///tmp/my_cluster ``` And then use the regular Docker commands. ```bash docker -H tcp:// info docker -H tcp:// run ... docker -H tcp:// ps docker -H tcp:// logs ... ... ``` You can list the nodes in your cluster. ```bash $ swarm list file:///tmp/my_cluster ``` ### 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. ```bash swarm join --advertise= etcd:/// ``` Start the manager on any machine or your laptop. ```bash swarm manage -H tcp:// etcd:/// ``` And then use the regular Docker commands. ```bash docker -H tcp:// info docker -H tcp:// run ... docker -H tcp:// ps docker -H tcp:// logs ... ... ``` You can list the nodes in your cluster. ```bash swarm list etcd:/// ``` ### 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. ```bash swarm join --advertise= consul:/// ``` Start the manager on any machine or your laptop. ```bash swarm manage -H tcp:// consul:/// ``` And then use the regular Docker commands. ```bash docker -H tcp:// info docker -H tcp:// run ... docker -H tcp:// ps docker -H tcp:// logs ... ... ``` You can list the nodes in your cluster. ```bash swarm list consul:/// ``` ### 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. ```bash swarm join --advertise= zk://,/ ``` Start the manager on any machine or your laptop. ```bash swarm manage -H tcp:// zk://,/ ``` You can then use the regular Docker commands. ```bash docker -H tcp:// info docker -H tcp:// run ... docker -H tcp:// ps docker -H tcp:// logs ... ... ``` You can list the nodes in the cluster. ```bash swarm list zk://,/ ``` ### Using a static list of IP addresses Start the manager on any machine or your laptop ```bash swarm manage -H nodes://, ``` Or ```bash swarm manage -H , ``` Then use the regular Docker commands. ```bash docker -H info docker -H run ... docker -H ps docker -H 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. ```bash $ 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. ```bash swarm manage -H tcp:// file:///tmp/my_cluster ``` And for the `nodes` discovery method. ```bash swarm manage -H "nodes://10.0.0.[10:200]:2375,10.0.1.[2:250]:2375" ``` ## Contributing a new discovery backend Contributing a new discovery backend is easy, simply implement this interface: ```go type Discovery interface { Initialize(string, int) error Fetch() ([]string, error) Watch(WatchCallback) Register(string) error } ``` ### Initialize The parameters are `discovery` location without the scheme and a heartbeat (in seconds). ### Fetch Returns the list of all the nodes from the discovery. ### Watch Triggers an update (`Fetch`). This can happen either via a timer (like `token`) or use backend specific features (like `etcd`). ### Register Add a new node to the discovery service. ## Docker Swarm documentation index - [User guide](./index.md) - [Scheduler strategies](./scheduler/strategy.md) - [Scheduler filters](./scheduler/filter.md) - [Swarm API](./API.md)