--- 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. It is not meant to be used in production scenarios but for development/testing only. 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](../docs/index.md) - [Scheduler strategies](../docs/scheduler/strategy.md) - [Scheduler filters](../docs/scheduler/filter.md) - [Swarm API](../docs/api/swarm-api.md)