mirror of https://github.com/docker/docs.git
Merge pull request #1718 from moxiegirl/swarm-1.10-docs
How to get Swarm and Machine provisioning
This commit is contained in:
Victor Vieux
commit
5557849a2c
|
|
@ -0,0 +1,126 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "How to get Swarm"
|
||||
description = "Running a Swarm container on Docker Engine. Run a Swarm binary on the host OS without Docker Engine."
|
||||
keywords = ["docker, Swarm, container, binary, clustering, install, installation"]
|
||||
[menu.main]
|
||||
identifier="how-to-get-and-run-Swarm"
|
||||
parent="mn_install"
|
||||
weight=9
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# How to get Docker Swarm
|
||||
|
||||
You can create a Docker Swarm cluster using the `swarm` executable image from a
|
||||
container or using an executable `swarm` binary you install on your system. This
|
||||
page introduces the two methods and discusses their pros and cons.
|
||||
|
||||
## Create a cluster with an interactive container
|
||||
|
||||
You can use the Docker Swarm official image to create a cluster. The image is
|
||||
built by Docker and updated regularly through an automated build. To use the
|
||||
image, you run it a container via the Engine `docker run` command. The image has
|
||||
multiple options and subcommands you can use to create and manage a Swarm cluster.
|
||||
|
||||
The first time you use any image, Docker Engine checks to see if you already have the image in your environment. By default Docker runs the `swarm:latest` version but you can also specify a tag other than `latest`. If you have an image locally but a newer one exists on Docker Hub, Engine downloads it.
|
||||
|
||||
### Run the Swarm image from a container
|
||||
|
||||
1. Open a terminal on a host running Engine.
|
||||
|
||||
If you are using Mac or Windows, then you must make sure you have started an Docker Engine host running and pointed your terminal environment to it with the Docker Machine commands. If you aren't sure, you can verify:
|
||||
|
||||
$ docker-machine ls
|
||||
NAME ACTIVE URL STATE URL SWARM DOCKER ERRORS
|
||||
default * virtualbox Running tcp://192.168.99.100:2376 v1.9.1
|
||||
|
||||
This shows an environment running an Engine host on the `default` instance.
|
||||
|
||||
2. Use the Swarm image to execute a command.
|
||||
|
||||
The easiest command is to get the help for the image. This command shows all the options that are available with the image.
|
||||
|
||||
$ docker run swarm --help
|
||||
Unable to find image 'swarm:latest' locally
|
||||
latest: Pulling from library/swarm
|
||||
d681c900c6e3: Pull complete
|
||||
188de6f24f3f: Pull complete
|
||||
90b2ffb8d338: Pull complete
|
||||
237af4efea94: Pull complete
|
||||
3b3fc6f62107: Pull complete
|
||||
7e6c9135b308: Pull complete
|
||||
986340ab62f0: Pull complete
|
||||
a9975e2cc0a3: Pull complete
|
||||
Digest: sha256:c21fd414b0488637b1f05f13a59b032a3f9da5d818d31da1a4ca98a84c0c781b
|
||||
Status: Downloaded newer image for swarm:latest
|
||||
Usage: swarm [OPTIONS] COMMAND [arg...]
|
||||
|
||||
A Docker-native clustering system
|
||||
|
||||
Version: 1.0.1 (744e3a3)
|
||||
|
||||
Options:
|
||||
--debug debug mode [$DEBUG]
|
||||
--log-level, -l "info" Log level (options: debug, info, warn, error, fatal, panic)
|
||||
--help, -h show help
|
||||
--version, -v print the version
|
||||
|
||||
Commands:
|
||||
create, c Create a cluster
|
||||
list, l List nodes in a cluster
|
||||
manage, m Manage a docker cluster
|
||||
join, j join a docker cluster
|
||||
help, h Shows a list of commands or help for one command
|
||||
|
||||
Run 'swarm COMMAND --help' for more information on a command.
|
||||
|
||||
In this example, the image did not exist on the Engine host, so the Engine
|
||||
downloaded it. After it downloaded, the `swarm` image executed the and
|
||||
displayed the help. After displaying the help, the `swarm` image exits and returns your to your terminal command line.
|
||||
|
||||
3. List the running containers on your Engine host.
|
||||
|
||||
$ docker ps
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
|
||||
Swarm is no longer running. The `swarm` image exits after you issue it a command.
|
||||
|
||||
### Why use the image?
|
||||
|
||||
Using a Swarm container has three key benefits over other methods:
|
||||
|
||||
* You don't need to install a binary on the system to use the image.
|
||||
* The single command `docker run` command gets and run the most recent version of the image every time.
|
||||
* The container isolates Swarm from your host environment. You don't need to perform or maintain shell paths and environments.
|
||||
|
||||
Running the Swarm image is the recommended way to create and manage your Swarm cluster. All of Docker's documentation and tutorials use this method.
|
||||
|
||||
## Run a Swarm binary
|
||||
|
||||
Before you run a Swarm binary directly on a host operating system (OS), you compile the binary from the source code or get a trusted copy from another location. Then you run the Swarm binary.
|
||||
|
||||
To compile Swarm from source code, refer to the instructions in
|
||||
[CONTRIBUTING.md](http://github.com/docker/swarm/blob/master/CONTRIBUTING.md).
|
||||
|
||||
|
||||
### Why use the binary?
|
||||
|
||||
Using a Swarm binary this way has one key benefit over other methods: If you are
|
||||
a developer who contributes to the Swarm project, you can test your code changes
|
||||
without "containerizing" the binary before you run it.
|
||||
|
||||
Running a Swarm binary on the host OS has disadvantages:
|
||||
|
||||
* Compilation from source is a burden.
|
||||
* The binary doesn't have the benefits that
|
||||
Docker containers provide, such as isolation.
|
||||
* Most Docker documentation and tutorials don't show this method of running swarm.
|
||||
|
||||
Lastly, because the Swarm nodes don't use Engine, you can't use Docker-based
|
||||
software tools, such as Docker Engine CLI at the node level.
|
||||
|
||||
## Related information
|
||||
|
||||
* [Docker Swarm official image](https://hub.docker.com/_/swarm/) repository on Docker Hub
|
||||
* [Provision a Swarm with Docker Machine](provision-with-machine.md)
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Swarm"
|
||||
title = "Docker Swarm"
|
||||
description = "Swarm: a Docker-native clustering system"
|
||||
keywords = ["docker, swarm, clustering"]
|
||||
[menu.main]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,190 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Provision with Machine"
|
||||
description = "Provision with Machine"
|
||||
keywords = ["docker, Swarm, clustering, provision, Machine"]
|
||||
[menu.main]
|
||||
parent="workw_swarm"
|
||||
weight=5
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# Provision a Swarm cluster with Docker Machine
|
||||
|
||||
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](install-w-machine.md) or [installing a Swarm for
|
||||
production](install-on-aws.md). If this is the first time you have used Machine,
|
||||
you should take some time to [understand Machine before
|
||||
continuing](https://docs.docker.com/machine).
|
||||
|
||||
|
||||
## What you need
|
||||
|
||||
If you are using Mac OS X or Windows and have installed with Docker Toolbox, you
|
||||
should already have Machine installed. If you need to install, see the
|
||||
instructions for [Mac OS X](https://docs.docker.com/engine/installation/mac/) or
|
||||
[Windows](https://docs.docker.com/engine/installation/mac/).
|
||||
|
||||
Machine supports installing on AWS, Digital Ocean, Google Cloud Platform, IBM
|
||||
Softlayer, Microsoft Azure and Hyper-V, OpenStack, Rackspace, VirtualBox, VMware
|
||||
Fusion®, vCloud® Air<sup>TM</sup> and vSphere®. In this example,
|
||||
you'll use VirtualBox to run several VMs based on the `boot2docker.iso` image.
|
||||
This image is a small-footprint Linux distribution for running Engine.
|
||||
|
||||
The Toolbox installation gives you VirtualBox and the `boot2docker.iso` image
|
||||
you need. It also gives you the ability provision on all the systems Machine
|
||||
supports.
|
||||
|
||||
**Note**:These examples assume you are using Mac OS X or Windows, if you like you can also [install Docker Machine directly on a Linux
|
||||
system](http://docs.docker.com/machine/install-machine).
|
||||
|
||||
## 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
|
||||
host called `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 `local` host.
|
||||
|
||||
```
|
||||
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
|
||||
`swarm` image:
|
||||
|
||||
```
|
||||
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 `SWARM_CLUSTER_TOKEN`.
|
||||
|
||||
## 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 master node on a new VM
|
||||
called `swarm-master`, you do the following:
|
||||
|
||||
```
|
||||
docker-machine create \
|
||||
-d virtualbox \
|
||||
--swarm \
|
||||
--swarm-master \
|
||||
--swarm-discovery token://SWARM_CLUSTER_TOKEN \
|
||||
swarm-master
|
||||
```
|
||||
|
||||
Then, provision additional an additional node. You must supply the
|
||||
`SWARM_CLUSTER_TOKEN` and a unique name for each host node, `HOST_NODE_NAME`.
|
||||
|
||||
```
|
||||
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
|
||||
example.
|
||||
|
||||
>**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](http://status.docker.com/) for service
|
||||
availability. If the problem 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-master"
|
||||
export DOCKER_MACHINE_NAME="swarm-master"
|
||||
# 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-master`, you would do
|
||||
this:
|
||||
|
||||
```
|
||||
eval "$(docker-machine env --swarm swarm-master)"
|
||||
```
|
||||
|
||||
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-master: 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-master
|
||||
```
|
||||
|
||||
## Related information
|
||||
|
||||
* [Evaluate Swarm in a sandbox](install-w-machine.md)
|
||||
* [Build a Swarm cluster for production](install-on-aws.md)
|
||||
* [Swarm Discovery](discovery.md)
|
||||
* [Docker Machine](https://docs.docker.com/machine) documentation
|
||||
Loading…
Reference in New Issue