Provision a Swarm cluster with Docker Machine
Estimated reading time: 5 minutes
You are viewing docs for legacy standalone Swarm. These topics describe standalone Docker Swarm. In Docker 1.12 and higher, Swarm mode is integrated with Docker Engine. Most users should use integrated Swarm mode — a good place to start is Getting started with swarm mode, Swarm mode CLI commands, and the Get started with Docker walkthrough). Standalone Docker Swarm is not integrated into the Docker Engine API and CLI commands.
You can use Docker Machine to provision a Docker Swarm cluster. Machine is the Docker provisioning tool. Machine provisions the hosts, installs Docker Engine on them, and then configures the Docker CLI client. With Machine’s Swarm options, you can also quickly configure a Swarm cluster as part of this provisioning.
This page explains the commands you need to provision a basic Swarm cluster on a local Mac or Windows computer using Machine. Once you understand the process, you can use it to setup a Swarm cluster on a cloud provider, or inside your company’s data center.
If this is the first time you are creating a Swarm cluster, you should first learn about Swarm and its requirements by installing a Swarm for evaluation or installing a Swarm for production. If this is the first time you have used Machine, you should take some time to understand Machine before continuing.
What you need
Machine supports installing on AWS, Digital Ocean, Google Cloud Platform, IBM
Softlayer, Microsoft Azure and Hyper-V, OpenStack, Rackspace, VirtualBox, VMware
Fusion®, vCloud® AirTM and vSphere®. In this example,
you’ll use VirtualBox to run several VMs based on the
This image is a small-footprint Linux distribution for running Engine.
The Toolbox installation gives you VirtualBox and the
you need. It also gives you the ability provision on all the systems Machine
Note: These examples assume you are using macOS or Windows, if you like you can also install Docker Machine directly on a Linux system.
Provision a host to generate a Swarm token
Before you can configure a Swarm, you start by provisioning a host with Engine.
Open a terminal on the host where you installed Machine. Then, to provision a
local, do the following:
docker-machine create -d virtualbox local
This examples uses VirtualBox but it could easily be DigitalOcean or a host on
your data center. The
local value is the host name. Once you create it,
configure your terminal’s shell environment to interact with the
eval "$(docker-machine env local)"
Each Swarm host has a token installed into its Engine configuration. The token
allows the Swarm discovery backend to recognize a node as belonging to a
particular Swarm cluster. Create the token for your cluster by running the
docker run swarm create Unable to find image 'swarm' locally 1.1.0-rc2: Pulling from library/swarm 892cb307750a: Pull complete fe3c9860e6d5: Pull complete cc01ef3f1fbc: Pull complete b7e14a9c9c72: Pull complete 3ec746117013: Pull complete 703cb7acfce6: Pull complete d4f6bb678158: Pull complete 2ad500e1bf96: Pull complete Digest: sha256:f02993cd1afd86b399f35dc7ca0240969e971c92b0232a8839cf17a37d6e7009 Status: Downloaded newer image for swarm 0de84fa62a1d9e9cc2156111f63ac31f
The output of the
swarm create command is a cluster token. Copy the token to a
safe place you will remember. Once you have the token, you can provision the
Swarm nodes and join them to the cluster_id. The rest of this documentation,
refers to this token as the
Provision Swarm nodes
All Swarm nodes in a cluster must have Engine installed. With Machine and the
SWARM_CLUSTER_TOKEN you can provision a host with Engine and configure it as a
Swarm node with one Machine command. To create a Swarm manager node on a new VM
swarm-manager, you do the following:
docker-machine create \ -d virtualbox \ --swarm \ --swarm-master \ --swarm-discovery token://SWARM_CLUSTER_TOKEN \ swarm-manager
Then, provision an additional node. You must supply the
SWARM_CLUSTER_TOKEN and a unique name for each host node,
docker-machine create \ -d virtualbox \ --swarm \ --swarm-discovery token://SWARM_CLUSTER_TOKEN \ HOST_NODE_NAME
For example, you might use
node-01 as the
HOST_NODE_NAME in the previous
Note: These command rely on Docker Swarm’s hosted discovery service, Docker Hub. If Docker Hub or your network is having issues, these commands may fail. Check the Docker Hub status page for service availability. If the problem is Docker Hub, you can wait for it to recover or configure other types of discovery backends.
Connect node environments with Machine
If you are connecting to typical host environment with Machine, you use the
env subcommand, like this:
eval "$(docker-machine env local)"
Docker Machine provides a special
--swarm flag with its
env command to
connect to Swarm nodes.
docker-machine env --swarm HOST_NODE_NAME export DOCKER_TLS_VERIFY="1" export DOCKER_HOST="tcp://192.168.99.101:3376" export DOCKER_CERT_PATH="/Users/mary/.docker/machine/machines/swarm-manager" export DOCKER_MACHINE_NAME="swarm-manager" # Run this command to configure your shell: # eval $(docker-machine env --swarm HOST_NODE_NAME)
To set your SHELL connect to a Swarm node called
swarm-manager, you would do
eval "$(docker-machine env --swarm swarm-manager)"
Now, you can use the Docker CLI to query and interact with your cluster.
docker info Containers: 2 Images: 1 Role: primary Strategy: spread Filters: health, port, dependency, affinity, constraint Nodes: 1 swarm-manager: 192.168.99.101:2376 └ Status: Healthy └ Containers: 2 └ Reserved CPUs: 0 / 1 └ Reserved Memory: 0 B / 1.021 GiB └ Labels: executiondriver=native-0.2, kernelversion=4.1.13-boot2docker, operatingsystem=Boot2Docker 1.9.1 (TCL 6.4.1); master : cef800b - Fri Nov 20 19:33:59 UTC 2015, provider=virtualbox, storagedriver=aufs CPUs: 1 Total Memory: 1.021 GiB Name: swarm-manager
- Evaluate Swarm in a sandbox
- Build a Swarm cluster for production
- Swarm discovery
- Docker Machine documentation