Docker Swarm: difference between --swarm-discovery and cluster-store

When creating a new swarm node we have something like the following code for the swarm master:

docker-machine create \
    -d digitalocean \
    --swarm \
    --swarm-master \
    --swarm-discovery="consul://${KV_IP}:8500" \
    --engine-opt="cluster-store=consul://${KV_IP}:8500" \
    --engine-opt="cluster-advertise=eth1:2376" \
    queenbee

What I don't understand is why we need both these lines?

--swarm-discovery="consul://${KV_IP}:8500" \
--engine-opt="cluster-store=consul://${KV_IP}:8500" \

What I have found so far is:

--swarm-discovery instructs the created Swarm worker container to look for the created key-value store using the specified address and protocol (consul:// here)
--cluster-store tells the Docker daemon which KV store to use for libnetwork’s needed coordination, similar to the --swarm-discovery option outlined above.

but their difference is still not clear to me.

Solution

You are basically correct.

The --swarm-discovery option is used to specify the key-value store that contains details of the Swarm nodes, and is used to manage the cluster service discovery. Note that this can even be a simple file with a list of nodes, or (not recommended) Docker Hub.

The --cluster-store option must be a libkv supported key-value store, however. This is used by Docker Engine to share details of containers, networks and volumes. This does not require Swarm, and it is perfectly possible to create a Docker cluster linked using Consul but that uses some alternative orchestration mechanism to Swarm. Generally, it is simplest for the Swarm and Docker cluster to share the same store, although it could also be possible to have different mechanisms for each.