docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revert install-w-machine.md to 833471b74c. 

Signed-off-by: Dong Chen <dongluo.chen@docker.com>
This commit is contained in:
Dong Chen 2016-08-03 17:40:32 -07:00
parent 9eae185fdd
commit 1c0b72c4db
2 changed files with 171 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/images/virtual-box.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 104 KiB

300
docs/install-w-machine.md
View File

@ -1,194 +1,236 @@
<!--[metadata]>
+++
title = "Evaluate Swarm in a sandbox"
description = "Evaluate Swarm in a sandbox"
keywords = ["docker, swarm, clustering, discovery, examples"]
title = "Install and use Swarm"
description = "Swarm release notes"
keywords = ["docker, swarm, clustering, discovery, release, notes"]
[menu.main]
parent="workw_swarm"
weight=-50
+++
<![end-metadata]-->
# Evaluate Swarm in a sandbox
# Install and Create a Docker Swarm
This getting started example shows you how to create a Docker Swarm, the
native clustering tool for Docker.
You use Docker Swarm to host and schedule a cluster of Docker containers. This section introduces you to Docker Swarm by teaching you how to create a swarm
on your local machine using Docker Machine and VirtualBox.
You'll use Docker Toolbox to install Docker Machine and some other tools on your computer. Then you'll use Docker Machine to provision a set of Docker Engine hosts. Lastly, you'll use Docker client to connect to the hosts, where you'll create a discovery token, create a cluster of one Swarm manager and nodes, and manage the cluster.
## Prerequisites
When you finish, you'll have a Docker Swarm up and running in VirtualBox on your
local Mac or Windows computer. You can use this Swarm as personal development
sandbox.
Make sure your local system has VirtualBox installed. If you are using Mac OS X
or Windows and have installed Docker, you should have VirtualBox already
installed.
To use Docker Swarm on Linux, see [Build a Swarm cluster for production](install-manual.md).
Using the instructions appropriate to your system architecture, [install Docker
Machine](http://docs.docker.com/machine/install-machine).
## Install Docker Toolbox
## Create a Docker Swarm
Download and install [Docker Toolbox](https://www.docker.com/docker-toolbox).
Docker Machine gets hosts ready to run Docker containers. Each node in your
Docker Swarm must have access to Docker to pull images and run them in
containers. Docker Machine manages all this provisioning for your swarm.
The toolbox installs a handful of tools on your local Windows or Mac OS X computer. In this exercise, you use three of those tools:
Before you create a swarm with `docker-machine`, you associate each
node with a discovery service. This example uses the token discovery
service hosted by Docker Hub (only for testing/dev, not for production).
This discovery service associates a token with instances of the Docker
Daemon running on each node. Other discovery service backends such as
`etcd`, `consul`, and `zookeeper` are [available](discovery.md).
- Docker Machine: To deploy virtual machines that run Docker Engine.
- VirtualBox: To host the virtual machines deployed from Docker Machine.
- Docker Client: To connect from your local computer to the Docker Engines on the VMs and issue docker commands to create the Swarm.
The following sections provide more information on each of these tools. The rest of the document uses the abbreviation, VM, for virtual machine.
## Create three VMs running Docker Engine
Here, you use Docker Machine to provision three VMs running Docker Engine.
1. Open a terminal on your computer. Use Docker Machine to list any VMs in VirtualBox.
1. List the machines on your system.
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
default * virtualbox Running tcp://192.168.99.100:2376
docker-vm * virtualbox Running tcp://192.168.99.100:2376
2. Optional: To conserve system resources, stop any virtual machines you are not using. For example, to stop the VM named `default`, enter:
This example was run a Mac OSX system with Docker Toolbox installed. So, the
`docker-vm` virtual machine is in the list.
$ docker-machine stop default
2. Create a VirtualBox machine called `local` on your system.
3. Create and run a VM named `manager`.
$ docker-machine create -d virtualbox local
INFO[0000] Creating SSH key...
INFO[0000] Creating VirtualBox VM...
INFO[0005] Starting VirtualBox VM...
INFO[0005] Waiting for VM to start...
INFO[0050] "local" has been created and is now the active machine.
INFO[0050] To point your Docker client at it, run this in your shell: eval "$(docker-machine env local)"
$ docker-machine create -d virtualbox manager
3. Load the `local` machine configuration into your shell.
4. Create and run a VM named `agent1`.
$ eval "$(docker-machine env local)"
$ docker-machine create -d virtualbox agent1
4. Generate a discovery token using the Docker Swarm image.
5. Create and run a VM named `agent2`.
The command below runs the `swarm create` command in a container. If you
haven't got the `swarm:latest` image on your local machine, Docker pulls it
for you.
$ docker-machine create -d virtualbox agent2
$ docker run swarm create
Unable to find image 'swarm:latest' locally
latest: Pulling from swarm
de939d6ed512: Pull complete
79195899a8a4: Pull complete
79ad4f2cc8e0: Pull complete
0db1696be81b: Pull complete
ae3b6728155e: Pull complete
57ec2f5f3e06: Pull complete
73504b2882a3: Already exists
swarm:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security.
Digest: sha256:aaaf6c18b8be01a75099cc554b4fb372b8ec677ae81764dcdf85470279a61d6f
Status: Downloaded newer image for swarm:latest
fe0cc96a72cf04dba8c1c4aa79536ec3
The `swarm create` command returned the `fe0cc96a72cf04dba8c1c4aa79536ec3`
token.
**Note**: This command relies on Docker Swarm's hosted discovery service. If
this service is having issues, this command may fail. In this case, see
information on using other types of [discovery backends](./discovery). Check
the [status page](http://status.docker.com/) for service availability.
5. Save the token in a safe place.
You'll use this token in the next step to create a Docker Swarm.
Each create command checks for a local copy of the *latest* VM image, called boot2docker.iso. If it isn't available, Docker Machine downloads the image from Docker Hub. Then, Docker Machine uses boot2docker.iso to create a VM that automatically runs Docker Engine.
## Launch the Swarm manager
> Troubleshooting: If your computer or hosts cannot reach Docker Hub, the
`docker-machine` or `docker run` commands that pull images may fail. In that
case, check the [Docker Hub status page](http://status.docker.com/) for
service availability. Then, check whether your computer is connected to the Internet. Finally, check whether VirtualBox's network settings allow your hosts to connect to the Internet.
A single system in your network is known as your Docker Swarm manager. The swarm
manager orchestrates and schedules containers on the entire cluster. The swarm
manager rules a set of agents (also called nodes or Docker nodes).
## Create a Swarm discovery token
Swarm agents are responsible for hosting containers. They are regular docker
daemons and you can communicate with them using the Docker remote API.
Here you use the discovery backend hosted on Docker Hub to create a unique discovery token for your cluster. This discovery backend is only for low-volume development and testing purposes, not for production. Later on, when you run the Swarm manager and nodes, they register with the discovery backend as members of the cluster that's associated with the unique token. The discovery backend maintains an up-to-date list of cluster members and shares that list with the Swarm manager. The Swarm manager uses this list to assign tasks to the nodes.
In this section, you create a swarm manager and two nodes.
1. Connect the Docker Client on your computer to the Docker Engine running on `manager`.
1. Create a swarm manager under VirtualBox.
$ eval $(docker-machine env manager)
docker-machine create \
-d virtualbox \
--swarm \
--swarm-master \
--swarm-discovery token://<TOKEN-FROM-ABOVE> \
swarm-master
The client will send the `docker` commands in the following steps to the Docker Engine on `manager`.
For example:
2. Create a unique id for the Swarm cluster.
$ docker-machine create -d virtualbox --swarm --swarm-master --swarm-discovery token://fe0cc96a72cf04dba8c1c4aa79536ec3 swarm-master
INFO[0000] Creating SSH key...
INFO[0000] Creating VirtualBox VM...
INFO[0005] Starting VirtualBox VM...
INFO[0005] Waiting for VM to start...
INFO[0060] "swarm-master" has been created and is now the active machine.
INFO[0060] To point your Docker client at it, run this in your shell: eval "$(docker-machine env swarm-master)"
$ docker run --rm swarm create
.
.
.
Status: Downloaded newer image for swarm:latest
0ac50ef75c9739f5bfeeaf00503d4e6e
2. Open your VirtualBox Manager, it should contain the `local` machine and the
new `swarm-master` machine.
The `docker run` command gets the latest `swarm` image and runs it as a container. The `create` argument makes the Swarm container connect to the Docker Hub discovery service and get a unique Swarm ID, also known as a "discovery token". The token appears in the output, it is not saved to a file on the host. The `--rm` option automatically cleans up the container and removes the file system when the container exits.
![VirtualBox](images/virtual-box.png)
The discovery service keeps unused tokens for approximately one week.
3. Create a swarm node.
3. Copy the discovery token from the last line of the previous output to a safe place.
docker-machine create \
-d virtualbox \
--swarm \
--swarm-discovery token://<TOKEN-FROM-ABOVE> \
swarm-agent-00
## Create the Swarm manager and nodes
For example:
Here, you connect to each of the hosts and create a Swarm manager or node.
$ docker-machine create -d virtualbox --swarm --swarm-discovery token://fe0cc96a72cf04dba8c1c4aa79536ec3 swarm-agent-00
INFO[0000] Creating SSH key...
INFO[0000] Creating VirtualBox VM...
INFO[0005] Starting VirtualBox VM...
INFO[0006] Waiting for VM to start...
INFO[0066] "swarm-agent-00" has been created and is now the active machine.
INFO[0066] To point your Docker client at it, run this in your shell: eval "$(docker-machine env swarm-agent-00)"
1. List the VMs to check that they're set up and running. For example:
3. Add another agent called `swarm-agent-01`.
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
agent1 - virtualbox Running tcp://192.168.99.102:2376 v1.9.1
agent2 - virtualbox Running tcp://192.168.99.103:2376 v1.9.1
manager * virtualbox Running tcp://192.168.99.100:2376 v1.9.1
$ docker-machine create -d virtualbox --swarm --swarm-discovery token://fe0cc96a72cf04dba8c1c4aa79536ec3 swarm-agent-01
You should see the two agents in your VirtualBox Manager.
## Direct your swarm
In this step, you connect to the swarm machine, display information related to
your swarm, and start an image on your swarm.
2. Your client should still be pointing to Docker Engine on `manager`. Use the following syntax to run a Swarm container that functions as the primary manager on `manager`.
1. Point your Docker environment to the machine running the swarm master.
$ docker run -d -p <your_selected_port>:3376 -t -v /var/lib/boot2docker:/certs:ro swarm manage -H 0.0.0.0:3376 --tlsverify --tlscacert=/certs/ca.pem --tlscert=/certs/server.pem --tlskey=/certs/server-key.pem token://<cluster_id>
$ eval $(docker-machine env --swarm swarm-master)
For example:
$ docker run -d -p 3376:3376 -t -v /var/lib/boot2docker:/certs:ro swarm manage -H 0.0.0.0:3376 --tlsverify --tlscacert=/certs/ca.pem --tlscert=/certs/server.pem --tlskey=/certs/server-key.pem token://0ac50ef75c9739f5bfeeaf00503d4e6e
2. Get information on your new swarm using the `docker` command.
The `-p` option maps a port 3376 on the container to port 3376 on the host. The `-v` option mounts the directory containing TLS certificates (`/var/lib/boot2docker` for the `manager` VM) into the container running Swarm manager in read-only mode.
$ docker info
Containers: 4
Strategy: spread
Filters: affinity, health, constraint, port, dependency
Nodes: 3
swarm-agent-00: 192.168.99.105:2376
└ Containers: 1
└ Reserved CPUs: 0 / 8
└ Reserved Memory: 0 B / 1.023 GiB
swarm-agent-01: 192.168.99.106:2376
└ Containers: 1
└ Reserved CPUs: 0 / 8
└ Reserved Memory: 0 B / 1.023 GiB
swarm-master: 192.168.99.104:2376
└ Containers: 2
└ Reserved CPUs: 0 / 8
3. Connect Docker Client to `agent1`.
You can see that each agent and the master all have port `2376` exposed. When you create a swarm, you can use any port you like and even different ports on different nodes. Each swarm node runs the swarm agent container.
$ eval $(docker-machine env agent1)
The master is running both the swarm manager and a swarm agent container. This isn't recommended in a production environment because it can cause problems with agent failover. However, it is perfectly fine to do this in a learning environment like this one.
4. Use the following syntax to run a Swarm container that functions as an agent on `agent1`. Replace `<node_ip>` with the IP address of the VM from above, or use the `docker-machine ip` command.
3. Check the images currently running on your swarm.
$ docker run -d swarm join --addr=<node_ip>:<node_port> token://<cluster_id>
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
78be991b58d1 swarm:latest "/swarm join --addr 3 minutes ago Up 2 minutes 2375/tcp swarm-agent-01/swarm-agent
da5127e4f0f9 swarm:latest "/swarm join --addr 6 minutes ago Up 6 minutes 2375/tcp swarm-agent-00/swarm-agent
ef395f316c59 swarm:latest "/swarm join --addr 16 minutes ago Up 16 minutes 2375/tcp swarm-master/swarm-agent
45821ca5208e swarm:latest "/swarm manage --tls 16 minutes ago Up 16 minutes 2375/tcp, 192.168.99.104:3376->3376/tcp swarm-master/swarm-agent-master
For example:
4. Run the Docker `hello-world` test image on your swarm.
$ docker run -d swarm join --addr=$(docker-machine ip agent1):2376 token://0ac50ef75c9739f5bfeeaf00503d4e6e
5. Connect Docker Client to `agent2`.
$ docker run hello-world
Hello from Docker.
This message shows that your installation appears to be working correctly.
$ eval $(docker-machine env agent2)
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(Assuming it was not already locally available.)
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
6. Run a Swarm container as an agent on `agent2`. For example:
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
$ docker run -d swarm join --addr=$(docker-machine ip agent2):2376 token://0ac50ef75c9739f5bfeeaf00503d4e6e
For more examples and ideas, visit:
http://docs.docker.com/userguide/
## Manage your Swarm
5. Use the `docker ps` command to find out which node the container ran on.
Here, you connect to the cluster and review information about the Swarm manager and nodes. You tell the Swarm to run a container and check which node did the work.
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
54a8690043dd hello-world:latest "/hello" 22 seconds ago Exited (0) 3 seconds ago swarm-agent-00/modest_goodall
78be991b58d1 swarm:latest "/swarm join --addr 5 minutes ago Up 4 minutes 2375/tcp swarm-agent-01/swarm-agent
da5127e4f0f9 swarm:latest "/swarm join --addr 8 minutes ago Up 8 minutes 2375/tcp swarm-agent-00/swarm-agent
ef395f316c59 swarm:latest "/swarm join --addr 18 minutes ago Up 18 minutes 2375/tcp swarm-master/swarm-agent
45821ca5208e swarm:latest "/swarm manage --tls 18 minutes ago Up 18 minutes 2375/tcp, 192.168.99.104:3376->3376/tcp swarm-master/swarm-agent-master
1. Connect the Docker Client to the Swarm by updating the `DOCKER_HOST` environment variable.
$ DOCKER_HOST=<manager_ip>:<your_selected_port>
We use the `docker-machine ip` command, and we selected port 3376 for the Swarm manager.
$ DOCKER_HOST=$(docker-machine ip manager):3376
Because Docker Swarm uses the standard Docker API, you can connect to it using Docker Client and other tools such as Docker Compose, Dokku, Jenkins, and Krane, among others.
2. Get information about the Swarm.
$ docker info
As you can see, the output displays information about the two agent nodes and the one manager node in the Swarm.
3. Check the images currently running on your Swarm.
$ docker ps
4. Run a container on the Swarm.
$ docker run hello-world
Hello from Docker.
.
.
.
5. Use the `docker ps` command to find out which node the container ran on. For example:
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
0b0628349187 hello-world "/hello" 20 minutes ago Exited (0) 11 seconds ago agent1
.
.
.
In this case, the Swarm ran `hello-world` on `agent1`.
By default, Docker Swarm uses the "spread" strategy to choose which node runs a container. When you run multiple containers, the spread strategy assigns each container to the node with the fewest containers.
## Where to go next
At this point, you've done the following:
- Created a Swarm discovery token.
- Created Swarm nodes using Docker Machine.
- Managed a Swarm cluster and run containers on it.
- Learned Swarm-related concepts and terminology.
However, Docker Swarm has many other aspects and capabilities.
For more information, visit [the Swarm landing page](https://www.docker.com/docker-swarm) or read the [Swarm documentation](https://docs.docker.com/swarm/).
At this point, you've installed Docker Swarm by pulling the latest image of
it from Docker Hub. Then, you built and ran a swarm on your local machine
using VirtualBox. If you want, you can onto read an [overview of Docker Swarm
features](index.md). Alternatively, you can develop a more in-depth view of Swarm by
[manually installing Swarm](install-manual.md) on a network.