beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

update cli commands output for rc1, revise key concepts

Browse source 
Signed-off-by: Charles Smith <charles.smith@docker.com>
(cherry picked from commit 9499d5fd52)
This commit is contained in:
Charles Smith 2016-06-15 13:26:13 -07:00 committed by Tibor Vass
parent e8e1fbb72f
commit dd39dbe79c
13 changed files with 289 additions and 257 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
docs/swarm/index.md
View file

@ -1,7 +1,7 @@
<!--[metadata]>
+++
title = "Swarm overview"
description = "Docker Swarm overview"
title = "Swarm mode overview"
description = "Docker Engine swarm mode overview"
keywords = ["docker, container, cluster, swarm"]
advisory = "rc"
[menu.main]
@ -10,16 +10,16 @@ parent="engine_swarm"
weight="1"
+++
<![end-metadata]-->
# Docker Swarm overview
# Swarm mode overview
To use this version of Swarm, install the Docker Engine `v1.12.0-rc1` or later
from the [Docker releases GitHub
To use Docker Engine in swarm mode, install the Docker Engine `v1.12.0-rc1` or
later from the [Docker releases GitHub
repository](https://github.com/docker/docker/releases). Alternatively, install
the latest Docker for Mac or Docker for Windows Beta.
Docker Engine 1.12 includes Docker Swarm for natively managing a cluster of
Docker Engines called a Swarm. Use the Docker CLI to create a Swarm, deploy
application services to the Swarm, and manage the Swarm behavior.
Docker Engine 1.12 includes swarm mode for natively managing a cluster of
Docker Engines called a Swarm. Use the Docker CLI to create a swarm, deploy
application services to a swarm, and manage swarm behavior.
If you’re using a Docker version prior to `v1.12.0-rc1`, see [Docker
@ -33,47 +33,52 @@ services. You don't need additional orchestration software to create or manage
a Swarm.
* **Decentralized design:** Instead of handling differentiation between node
roles at deployment time, Swarm handles any specialization at runtime. You can
deploy both kinds of nodes, managers and workers, using the Docker Engine.
This means you can build an entire Swarm from a single disk image.
roles at deployment time, the Docker Engine handles any specialization at
runtime. You can deploy both kinds of nodes, managers and workers, using the
Docker Engine. This means you can build an entire Swarm from a single disk
image.
* **Declarative service model:** Swarm uses a declarative syntax to let you
define the desired state of the various services in your application stack.
For example, you might describe an application comprised of a web front end
service with message queueing services and a database backend.
* **Declarative service model:** Docker Engine uses a declarative approach to
let you define the desired state of the various services in your application
stack. For example, you might describe an application comprised of a web front
end service with message queueing services and a database backend.
* **Desired state reconciliation:** Swarm constantly monitors the cluster state
and reconciles any differences between the actual state your expressed desired
state.
* **Scaling:** For each service, you can declare the number of tasks you want to
run. When you scale up or down, the swarm manager automatically adapts by
adding or removing tasks to maintain the desired state.
* **Desired state reconciliation:** The swarm manager node constantly monitors
the cluster state and reconciles any differences between the actual state your
expressed desired state. For example, if you set up a service to run 10
replicas of a container, and a worker machine hosting two of those replicas
crashes, the manager will create two new replicas to replace the ones that
crashed. The swarm manager assigns the new replicas to workers that are
running and available.
* **Multi-host networking:** You can specify an overlay network for your
application. Swarm automatically assigns addresses to the containers on the
overlay network when it initializes or updates the application.
services. The swarm manager automatically assigns addresses to the containers
on the overlay network when it initializes or updates the application.
* **Service discovery:** Swarm assigns each service a unique DNS name and load
balances running containers. Each Swarm has an internal DNS server that can
query every container in the cluster using DNS.
* **Service discovery:** Swarm manager nodes assign each service in the swarm a
unique DNS name and load balances running containers. You can query every
container running in the swarm through a DNS server embedded in the swarm.
* **Load balancing:** Using Swarm, you can expose the ports for services to an
external load balancer. Internally, Swarm lets you specify how to distribute
* **Load balancing:** You can expose the ports for services to an
external load balancer. Internally, the swarm lets you specify how to distribute
service containers between nodes.
* **Secure by default:** Each node in the Swarm enforces TLS mutual
* **Secure by default:** Each node in the swarm enforces TLS mutual
authentication and encryption to secure communications between itself and all
other nodes. You have the option to use self-signed root certificates or
certificates from a custom root CA.
* **Scaling:** For each service, you can declare the number of instances you
want to run. When you scale up or down, Swarm automatically adapts by adding
or removing instances of the service to maintain the desired state.
* **Rolling updates:** At rollout time you can apply service updates to nodes
incrementally. Swarm lets you control the delay between service deployment to
different sets of nodes. If anything goes wrong, you can roll-back an instance
of a service.
incrementally. The swarm manager lets you control the delay between service
deployment to different sets of nodes. If anything goes wrong, you can
roll-back a task to a previous version of the service.
## What's next?
* Learn Swarm [key concepts](key-concepts.md).
* Get started with the [Swarm tutorial](swarm-tutorial/index.md).
* Learn swarm mode [key concepts](key-concepts.md).
* Get started with the [swarm mode tutorial](swarm-tutorial/index.md).
<p style="margin-bottom:300px">&nbsp;</p>

111
docs/swarm/key-concepts.md
View file

@ -1,86 +1,93 @@
<!--[metadata]>
+++
title = "Swarm key concepts"
description = "Introducing key concepts for Docker Swarm"
keywords = ["docker, container, cluster, swarm"]
title = "Swarm mode key concepts"
description = "Introducing key concepts for Docker Engine swarm mode"
keywords = ["docker, container, cluster, swarm mode"]
advisory = "rc"
[menu.main]
identifier="swarm-concepts"
identifier="swarm-mode-concepts"
parent="engine_swarm"
weight="2"
+++
<![end-metadata]-->
# Docker Swarm key concepts
# Swarm mode key concepts
Building upon the core features of Docker Engine, Docker Swarm enables you to
create a Swarm of Docker Engines and orchestrate services to run in the Swarm.
This topic describes key concepts to help you begin using Docker Swarm.
This topic introduces some of the concepts unique to the cluster management and
orchestration features of Docker Engine 1.12.
## Swarm
**Docker Swarm** is the name for the cluster management and orchestration
features embedded in the Docker Engine. Engines that are participating in a
cluster are running in **Swarm mode**.
The cluster management and orchestration features embedded in the Docker Engine
are built using **SwarmKit**. Engines participating in a cluster are
running in **swarm mode**. You enable swarm mode for the Engine by either
initializing a swarm or joining an existing swarm.
A **Swarm** is a cluster of Docker Engines where you deploy a set of application
services. When you deploy an application to a Swarm, you specify the desired
state of the services, such as which services to run and how many instances of
those services. The Swarm takes care of all orchestration duties required to
keep the services running in the desired state.
A **swarm** is a self-organizing cluster of Docker Engines where you deploy
[services](#Services-and-tasks). The Docker Engine CLI includes the commands for
swarm management, such as adding and removing nodes. The CLI also includes the
commands you need to deploy services to the swarm and manage service
orchestration.
When you run Docker Engine outside of swarm mode, you execute container
commands. When you run the Engine in swarm mode, you orchestrate services.
## Node
A **node** is an active instance of the Docker Engine in the Swarm.
A **node** is an instance of the Docker Engine participating in the swarm.
When you deploy your application to a Swarm, **manager nodes** accept the
service definition that describes the Swarm's desired state. Manager nodes also
perform the orchestration and cluster management functions required to maintain
the desired state of the Swarm. For example, when a manager node receives notice
to deploy a web server, it dispatches the service tasks to worker nodes.
To deploy your application to a swarm, you submit a service definition to a
**manager node**. The manager node dispatches units of work called
[tasks](#Services-and-tasks) to worker nodes.
By default the Docker Engine starts one manager node for a Swarm, but as you
scale you can add more managers to make the cluster more fault-tolerant. If you
require high availability Swarm management, Docker recommends three or five
Managers in your cluster.
Because Swarm manager nodes share data using Raft, there must be an odd number
of managers. The Swarm cluster can continue functioning in the face of up to
`N/2` failures where `N` is the number of manager nodes. More than five
managers is likely to degrade cluster performance and is not recommended.
Manager nodes also perform the orchestration and cluster management functions
required to maintain the desired state of the swarm. Manager nodes elect a single leader to conduct orchestration tasks.
**Worker nodes** receive and execute tasks dispatched from manager nodes. By
default manager nodes are also worker nodes, but you can configure managers to
be manager-only nodes.
be manager-only nodes. The agent notifies the manager node of the current
state of its assigned tasks so the manager can maintain the desired state.
## Services and tasks
A **service** is the definition of how to run the various tasks that make up
your application. For example, you may create a service that deploys a Redis
image in your Swarm.
A **service** is the definition of the tasks to execute on the worker nodes. It
is the central structure of the swarm system and the primary root of user
interaction with the swarm.
A **task** is the atomic scheduling unit of Swarm. For example a task may be to
schedule a Redis container to run on a worker node.
When you create a service, you specify which container image to use and which
commands to execute inside running containers.
In the **replicated services** model, the swarm manager distributes a specific
number of replica tasks among the nodes based upon the scale you set in the
desired state.
## Service types
For **global services**, the swarm runs one task for the service on every
available node in the cluster.
For **replicated services**, Swarm deploys a specific number of replica tasks
based upon the scale you set in the desired state.
For **global services**, Swarm runs one task for the service on every available
node in the cluster.
A **task** carries a Docker container and the commands to run inside the
container. It is the atomic scheduling unit of swarm. Manager nodes assign tasks
to worker nodes according to the number of replicas set in the service scale.
Once a task is assigned to a node, it cannot move to another node. It can only
run on the assigned node or fail.
## Load balancing
Swarm uses **ingress load balancing** to expose the services you want to make
available externally to the Swarm. Swarm can automatically assign the service a
**PublishedPort** or you can configure a PublishedPort for the service in the
30000-32767 range. External components, such as cloud load balancers, can access
the service on the PublishedPort of any node in the cluster, even if the node is
not currently running the service.
The swarm manager uses **ingress load balancing** to expose the services you
want to make available externally to the swarm. The swarm manager can
automatically assign the service a **PublishedPort** or you can configure a
PublishedPort for the service in the 30000-32767 range.
Swarm has an internal DNS component that automatically assigns each service in
the Swarm DNS entry. Swarm uses **internal load balancing** distribute requests
among services within the cluster based upon the services' DNS name.
External components, such as cloud load balancers, can access the service on the
PublishedPort of any node in the cluster whether or not the node is currently
running the task for the service. All nodes in the swarm cluster route ingress
connections to a running task instance.
Swarm mode has an internal DNS component that automatically assigns each service
in the swarm DNS entry. The swarm manager uses **internal load balancing**
distribute requests among services within the cluster based upon the DNS name of
the service.
## What's next?
* Read the [swarm mode overview](index.md).
* Get started with the [swarm mode tutorial](swarm-tutorial/index.md).
<p style="margin-bottom:300px">&nbsp;</p>

6
docs/swarm/menu.md
View file

@ -16,6 +16,6 @@ weight = 0
This section contains the following topics:
* [Docker Swarm overview](index.md)
* [Docker Swarm key concepts](key-concepts.md)
* [Getting Started with Docker Swarm](swarm-tutorial/index.md)
* [Docker swarm mode overview](index.md)
* [Docker swarm mode key concepts](key-concepts.md)
* [Getting Started with Docker swarm mode](swarm-tutorial/index.md)

28
docs/swarm/swarm-tutorial/add-nodes.md
View file

@ -1,7 +1,7 @@
<!--[metadata]>
+++
title = "Add nodes to the Swarm"
description = "Add nodes to the Swarm"
title = "Add nodes to the swarm"
description = "Add nodes to the swarm"
keywords = ["tutorial, cluster management, swarm"]
advisory = "rc"
[menu.main]
@ -11,16 +11,16 @@ weight=13
+++
<![end-metadata]-->
# Add nodes to the Swarm
# Add nodes to the swarm
Once you've [created a Swarm](create-swarm.md) with a manager node, you're ready
Once you've [created a swarm](create-swarm.md) with a manager node, you're ready
to add worker nodes.
1. Open a terminal and ssh into the machine where you want to run a worker node.
This tutorial uses the name `worker1`.
2. Run the following command to create a worker node joined to
the existing Swarm:
the existing swarm:
```
docker swarm join <MANAGER-IP>:<PORT>
@ -29,7 +29,7 @@ the existing Swarm:
Replace `<MANAGER-IP>` with the address of the manager node and `<PORT>`
with the port where the manager listens.
In the tutorial, the following command joins `worker1` to the Swarm on `manager1`:
In the tutorial, the following command joins `worker1` to the swarm on `manager1`:
```
$ docker swarm join 192.168.99.100:2377
@ -50,15 +50,13 @@ the existing Swarm.
the `docker node ls` command to see the worker nodes:
```bash
$ docker node ls
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
09fm6su6c24q * manager1 Accepted Ready Active Reachable Yes
32ljq6xijzb9 worker1 Accepted Ready Active
38fsncz6fal9 worker2 Accepted Ready Active
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
03g1y59jwfg7cf99w4lt0f662 worker2 Accepted Ready Active
9j68exjopxe7wfl6yuxml7a7j worker1 Accepted Ready Active
dxn1zf6l61qsb1josjja83ngz * manager1 Accepted Ready Active Reachable Yes
```
The `MANAGER` column identifies the manager nodes in the Swarm. The empty
The `MANAGER` column identifies the manager nodes in the swarm. The empty
status in this column for `worker1` and `worker2` identifies them as worker nodes.
Swarm management commands like `docker node ls` only work on manager nodes.
@ -66,7 +64,7 @@ the `docker node ls` command to see the worker nodes:
## What's next?
Now your Swarm consists of a manager and two worker nodes. In the next step of
the tutorial, you [deploy a service](deploy-service.md) to the Swarm.
Now your swarm consists of a manager and two worker nodes. In the next step of
the tutorial, you [deploy a service](deploy-service.md) to the swarm.
<p style="margin-bottom:300px">&nbsp;</p>

35
docs/swarm/swarm-tutorial/create-swarm.md
View file

@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "Create a Swarm"
description = "Initialize the Swarm"
keywords = ["tutorial, cluster management, swarm"]
title = "Create a swarm"
description = "Initialize the swarm"
keywords = ["tutorial, cluster management, swarm mode"]
advisory = "rc"
[menu.main]
identifier="initialize-swarm"
@ -11,34 +11,34 @@ weight=12
+++
<![end-metadata]-->
# Create a Swarm
# Create a swarm
After you complete the [tutorial setup](index.md) steps, you're ready
to create a Swarm. Make sure the Docker Engine daemon is started on the host
to create a swarm. Make sure the Docker Engine daemon is started on the host
machines.
1. Open a terminal and ssh into the machine where you want to run your manager
node. For example, the tutorial uses a machine named `manager1`.
2. Run the following command to create a new Swarm:
2. Run the following command to create a new swarm:
```
docker swarm init --listen-addr <MANAGER-IP>:<PORT>
```
In the tutorial, the following command creates a Swarm on the `manager1` machine:
In the tutorial, the following command creates a swarm on the `manager1` machine:
```
$ docker swarm init --listen-addr 192.168.99.100:2377
Swarm initialized: current node (09fm6su6c24qn) is now a manager.
Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.
```
The `--listen-addr` flag configures the manager node to listen on port
`2377`. The other nodes in the Swarm must be able to access the manager at
`2377`. The other nodes in the swarm must be able to access the manager at
the IP address.
3. Run `docker info` to view the current state of the Swarm:
3. Run `docker info` to view the current state of the swarm:
```
$ docker info
@ -48,11 +48,12 @@ node. For example, the tutorial uses a machine named `manager1`.
Paused: 0
Stopped: 2
...snip...
Swarm:
NodeID: 09fm6su6c24qn
IsManager: YES
Swarm: active
NodeID: dxn1zf6l61qsb1josjja83ngz
IsManager: Yes
Managers: 1
Nodes: 1
CACertHash: sha256:b7986d3baeff2f5664dfe350eec32e2383539ec1a802ba541c4eb829056b5f61
...snip...
```
@ -61,16 +62,16 @@ node. For example, the tutorial uses a machine named `manager1`.
```
$ docker node ls
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
09fm6su6c24q * manager1 Accepted Ready Active Reachable Yes
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
dxn1zf6l61qsb1josjja83ngz * manager1 Accepted Ready Active Reachable Yes
```
The `*` next to the node id, indicates that you're currently connected on
this node.
Docker Swarm automatically names the node for the machine host name. The
tutorial covers other columns in later steps.
Docker Engine swarm mode automatically names the node for the machine host
name. The tutorial covers other columns in later steps.
## What's next?

11
docs/swarm/swarm-tutorial/delete-service.md
View file

@ -1,7 +1,7 @@
<!--[metadata]>
+++
title = "Delete the service"
description = "Remove the service on the Swarm"
description = "Remove the service from the swarm"
keywords = ["tutorial, cluster management, swarm, service"]
advisory = "rc"
[menu.main]
@ -11,10 +11,10 @@ weight=19
+++
<![end-metadata]-->
# Delete the service running on the Swarm
# Delete the service running on the swarm
The remaining steps in the tutorial don't use the `helloworld` service, so now
you can delete the service from the Swarm.
you can delete the service from the swarm.
1. If you haven't already, open a terminal and ssh into the machine where you
run your manager node. For example, the tutorial uses a machine named
@ -24,11 +24,12 @@ run your manager node. For example, the tutorial uses a machine named
```
$ docker service rm helloworld
helloworld
```
3. Run `docker service inspect <SERVICE-ID>` to veriy that Swarm removed the
service. The CLI returns a message that the service is not found:
3. Run `docker service inspect <SERVICE-ID>` to veriy that the swarm manager
removed the service. The CLI returns a message that the service is not found:
```
$ docker service inspect helloworld

18
docs/swarm/swarm-tutorial/deploy-service.md
View file

@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "Deploy a service"
description = "Deploy the application"
keywords = ["tutorial, cluster management, swarm"]
description = "Deploy a service to the swarm"
keywords = ["tutorial, cluster management, swarm mode"]
advisory = "rc"
[menu.main]
identifier="deploy-application"
@ -11,10 +11,10 @@ weight=16
+++
<![end-metadata]-->
# Deploy a service to the Swarm
# Deploy a service to the swarm
After you [create a Swarm](create-swarm.md), you can deploy a service to the
Swarm. For this tutorial, you also [added worker nodes](add-nodes.md), but that
After you [create a swarm](create-swarm.md), you can deploy a service to the
swarm. For this tutorial, you also [added worker nodes](add-nodes.md), but that
is not a requirement to deploy a service.
1. Open a terminal and ssh into the machine where you run your manager node. For
@ -25,7 +25,7 @@ example, the tutorial uses a machine named `manager1`.
```bash
$ docker service create --replicas 1 --name helloworld alpine ping docker.com
2zs4helqu64f3k3iuwywbk49w
9uk4639qpg7npwf3fn2aasksr
```
* The `docker service create` command creates the service.
@ -39,12 +39,12 @@ example, the tutorial uses a machine named `manager1`.
```
$ docker service ls
ID NAME REPLICAS IMAGE COMMAND
2zs4helqu64f helloworld 1 alpine ping docker.com
ID NAME SCALE IMAGE COMMAND
9uk4639qpg7n helloworld 1/1 alpine ping docker.com
```
## What's next?
Now you've deployed a service to the Swarm, you're ready to [inspect the service](inspect-service.md).
Now you've deployed a service to the swarm, you're ready to [inspect the service](inspect-service.md).
<p style="margin-bottom:300px">&nbsp;</p>

66
docs/swarm/swarm-tutorial/drain-node.md
View file

@ -3,7 +3,7 @@
title = "Drain a node"
description = "Drain nodes on the Swarm"
keywords = ["tutorial, cluster management, swarm, service, drain"]
advisory = "rc"
advisory="rc"
[menu.main]
identifier="swarm-tutorial-drain-node"
parent="swarm-tutorial"
@ -11,15 +11,15 @@ weight=21
+++
<![end-metadata]-->
# Drain a node on the Swarm
# Drain a node on the swarm
In earlier steps of the tutorial, all the nodes have been running with `ACTIVE`
availability. The Swarm manager can assign tasks to any `ACTIVE` node, so all
nodes have been available to receive tasks.
availability. The swarm manager can assign tasks to any `ACTIVE` node, so up to
now all nodes have been available to receive tasks.
Sometimes, such as planned maintenance times, you need to set a node to `DRAIN`
availabilty. `DRAIN` availabilty prevents a node from receiving new tasks
from the Swarm manager. It also means the manager stops tasks running on the
availability. `DRAIN` availability prevents a node from receiving new tasks
from the swarm manager. It also means the manager stops tasks running on the
node and launches replica tasks on a node with `ACTIVE` availability.
1. If you haven't already, open a terminal and ssh into the machine where you
@ -28,13 +28,13 @@ run your manager node. For example, the tutorial uses a machine named
2. Verify that all your nodes are actively available.
```
```bash
$ docker node ls
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
1x2bldyhie1cj worker1 Accepted Ready Active
1y3zuia1z224i worker2 Accepted Ready Active
2p5bfd34mx4op * manager1 Accepted Ready Active Reachable Yes
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
1bcef6utixb0l0ca7gxuivsj0 worker2 Accepted Ready Active
38ciaotwjuritcdtn9npbnkuz worker1 Accepted Ready Active
e216jshn25ckzbvmwlnh5jr3g * manager1 Accepted Ready Active Reachable Yes
```
2. If you aren't still running the `redis` service from the [rolling
@ -43,22 +43,22 @@ update](rolling-update.md) tutorial, start it now:
```bash
$ docker service create --replicas 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
69uh57k8o03jtqj9uvmteodbb
c5uo6kdmzpon37mgj9mwglcfw
```
3. Run `docker service tasks redis` to see how the Swarm manager assigned the
tasks to different nodes:
```
```bash
$ docker service tasks redis
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
3wfqsgxecktpwoyj2zjcrcn4r redis.1 redis redis:3.0.6 RUNNING 13 minutes RUNNING worker2
8lcm041z3v80w0gdkczbot0gg redis.2 redis redis:3.0.6 RUNNING 13 minutes RUNNING worker1
d48skceeph9lkz4nbttig1z4a redis.3 redis redis:3.0.6 RUNNING 12 minutes RUNNING manager1
7q92v0nr1hcgts2amcjyqg3pq redis.1 redis redis:3.0.6 Running 26 seconds Running manager1
7h2l8h3q3wqy5f66hlv9ddmi6 redis.2 redis redis:3.0.6 Running 26 seconds Running worker1
9bg7cezvedmkgg6c8yzvbhwsd redis.3 redis redis:3.0.6 Running 26 seconds Running worker2
```
In this case the Swarm manager distributed one task to each node. You may
In this case the swarm manager distributed one task to each node. You may
see the tasks distributed differently among the nodes in your environment.
4. Run `docker node update --availability drain <NODE-ID>` to drain a node that
@ -66,18 +66,20 @@ had a task assigned to it:
```bash
docker node update --availability drain worker1
worker1
```
5. Inspect the node to check its availability:
```
```bash
$ docker node inspect --pretty worker1
ID: 1x2bldyhie1cj
ID: 38ciaotwjuritcdtn9npbnkuz
Hostname: worker1
Status:
State: READY
Availability: DRAIN
State: Ready
Availability: Drain
...snip...
```
@ -86,11 +88,13 @@ had a task assigned to it:
6. Run `docker service tasks redis` to see how the Swarm manager updated the
task assignments for the `redis` service:
```
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
3wfqsgxecktpwoyj2zjcrcn4r redis.1 redis redis:3.0.6 RUNNING 26 minutes RUNNING worker2
ah7o4u5upostw3up1ns9vbqtc redis.2 redis redis:3.0.6 RUNNING 9 minutes RUNNING manager1
d48skceeph9lkz4nbttig1z4a redis.3 redis redis:3.0.6 RUNNING 26 minutes RUNNING manager1
```bash
$ docker service tasks redis
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
7q92v0nr1hcgts2amcjyqg3pq redis.1 redis redis:3.0.6 Running 4 minutes Running manager1
b4hovzed7id8irg1to42egue8 redis.2 redis redis:3.0.6 Running About a minute Running worker2
9bg7cezvedmkgg6c8yzvbhwsd redis.3 redis redis:3.0.6 Running 4 minutes Running worker2
```
The Swarm manager maintains the desired state by ending the task on a node
@ -102,18 +106,20 @@ drained node to an active state:
```bash
$ docker node update --availability active worker1
worker1
```
8. Inspect the node to see the updated state:
```
```bash
$ docker node inspect --pretty worker1
ID: 1x2bldyhie1cj
ID: 38ciaotwjuritcdtn9npbnkuz
Hostname: worker1
Status:
State: READY
Availability: ACTIVE
State: Ready
Availability: Active
...snip...
```

41
docs/swarm/swarm-tutorial/index.md
View file

@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "Set up for the tutorial"
description = "Getting Started tutorial for Docker Swarm"
keywords = ["tutorial, cluster management, swarm"]
description = "Getting Started tutorial for Docker Engine swarm mode"
keywords = ["tutorial, cluster management, swarm mode"]
advisory = "rc"
[menu.main]
identifier="tutorial-setup"
@ -11,15 +11,18 @@ weight=11
+++
<![end-metadata]-->
# Getting Started with Docker Swarm
# Getting started with swarm mode
This tutorial introduces you to the key features of Docker Swarm. It guides you
through the following activities:
This tutorial introduces you to the features of Docker Engine Swarm mode. You
may want to familiarize yourself with the [key concepts](../key-concepts.md)
before you begin.
* initializing a cluster of Docker Engines called a Swarm
* adding nodes to the Swarm
* deploying application services to the Swarm
* managing the Swarm once you have everything running
The tutorial guides you through the following activities:
* initializing a cluster of Docker Engines in swarm mode
* adding nodes to the swarm
* deploying application services to the swarm
* managing the swarm once you have everything running
This tutorial uses Docker Engine CLI commands entered on the command line of a
terminal window. You should be able to install Docker on networked machines and
@ -28,6 +31,7 @@ be comfortable running commands in the shell of your choice.
If you’re brand new to Docker, see [About Docker Engine](../../index.md).
## Set up
To run this tutorial, you need the following:
* [three networked host machines](#three-networked-host-machines)
@ -37,7 +41,7 @@ To run this tutorial, you need the following:
### Three networked host machines
The tutorial uses three networked host machines as nodes in the Swarm. These can
The tutorial uses three networked host machines as nodes in the swarm. These can
be virtual machines on your PC, in a data center, or on a cloud service
provider. This tutorial uses the following machine names:
@ -47,10 +51,13 @@ provider. This tutorial uses the following machine names:
### Docker Engine 1.12 or later
You must install Docker Engine on each one of the host machines. To use this
version of Swarm, install the Docker Engine `v1.12.0-rc1` or later from the
[Docker releases GitHub repository](https://github.com/docker/docker/releases).
Alternatively, install the latest Docker for Mac or Docker for Windows Beta.
You must install Docker Engine on each one of the host machines. To use swarm
mode, install the Docker Engine `v1.12.0-rc1` or later from the [Docker releases
GitHub repository](https://github.com/docker/docker/releases). Alternatively,
install the latest Docker for Mac or Docker for Windows Beta.
>**Advisory**: Some multi-node features may not work for Docker for Mac Beta and
Docker for Windows Beta. We're working on the multi-node features for GA.
Verify that the Docker Engine daemon is running on each of the machines.
@ -64,9 +71,9 @@ Verify that the Docker Engine daemon is running on each of the machines.
### The IP address of the manager machine
The IP address must be assigned to an a network interface available to the host
operating system. All nodes in the Swarm must be able to access the manager at the IP address.
operating system. All nodes in the swarm must be able to access the manager at the IP address.
>**Tip**: You can run `ifconfig` on Linux or Mac OSX to see a list of the
>**Tip**: You can run `ifconfig` on Linux or Mac OS X to see a list of the
available network interfaces.
The tutorial uses `manager1` : `192.168.99.100`.
@ -82,6 +89,6 @@ The tutorial uses `manager1` : `192.168.99.100`.
## What's next?
After you have set up your environment, you're ready to [create a Swarm](create-swarm.md).
After you have set up your environment, you're ready to [create a swarm](create-swarm.md).
<p style="margin-bottom:300px">&nbsp;</p>

67
docs/swarm/swarm-tutorial/inspect-service.md
View file

@ -2,7 +2,7 @@
+++
title = "Inspect the service"
description = "Inspect the application"
keywords = ["tutorial, cluster management, swarm"]
keywords = ["tutorial, cluster management, swarm mode"]
advisory = "rc"
[menu.main]
identifier="inspect-application"
@ -11,10 +11,10 @@ weight=17
+++
<![end-metadata]-->
# Inspect a service on the Swarm
# Inspect a service on the swarm
When you have [deployed a service](deploy-service.md) to your Swarm, you can use
the Docker CLI to see details about the service running in the Swarm.
When you have [deployed a service](deploy-service.md) to your swarm, you can use
the Docker CLI to see details about the service running in the swarm.
1. If you haven't already, open a terminal and ssh into the machine where you
run your manager node. For example, the tutorial uses a machine named
@ -28,17 +28,17 @@ about a service in an easily readable format.
```
$ docker service inspect --pretty helloworld
ID: 2zs4helqu64f3k3iuwywbk49w
ID: 9uk4639qpg7npwf3fn2aasksr
Name: helloworld
Mode: REPLICATED
Scale: 1
Replicas: 1
Placement:
Strategy: SPREAD
UpdateConfig:
Parallelism: 1
ContainerSpec:
Image: alpine
Command: ping docker.com
Args: ping docker.com
```
>**Tip**: To return the service details in json format, run the same command
@ -48,36 +48,43 @@ about a service in an easily readable format.
$ docker service inspect helloworld
[
{
"ID": "2zs4helqu64f3k3iuwywbk49w",
"ID": "9uk4639qpg7npwf3fn2aasksr",
"Version": {
"Index": 16264
"Index": 418
},
"CreatedAt": "2016-06-06T17:41:11.509146705Z",
"UpdatedAt": "2016-06-06T17:41:11.510426385Z",
"CreatedAt": "2016-06-16T21:57:11.622222327Z",
"UpdatedAt": "2016-06-16T21:57:11.622222327Z",
"Spec": {
"Name": "helloworld",
"ContainerSpec": {
"Image": "alpine",
"Command": [
"ping",
"docker.com"
],
"TaskTemplate": {
"ContainerSpec": {
"Image": "alpine",
"Args": [
"ping",
"docker.com"
]
},
"Resources": {
"Limits": {},
"Reservations": {}
}
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": {}
},
"Mode": {
"Replicated": {
"Instances": 1
"Replicas": 1
}
},
"RestartPolicy": {},
"Placement": {},
"UpdateConfig": {
"Parallelism": 1
},
"EndpointSpec": {}
"EndpointSpec": {
"Mode": "vip"
}
},
"Endpoint": {
"Spec": {}
@ -92,20 +99,20 @@ service:
```
$ docker service tasks helloworld
ID NAME SERVICE IMAGE DESIRED STATE LAST STATE NODE
1n6wif51j0w840udalgw6hphg helloworld.1 helloworld alpine RUNNING RUNNING 19 minutes manager1
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
8p1vev3fq5zm0mi8g0as41w35 helloworld.1 helloworld alpine Running 3 minutes Running worker2
```
In this case, the one instance of the `helloworld` service is running on the
`manager1` node. Manager nodes in a Swarm can execute tasks just like worker
nodes.
`worker2` node. You may see the service running on your manager node. By
default, manager nodes in a Swarm can execute tasks just like worker nodes.
Swarm also shows you the `DESIRED STATE` and `LAST STATE` of the service
task so you can see if tasks are running according to the service
definition.
4. Run `docker ps` on the node where the instance of the service is running to
see the service container.
4. Run `docker ps` on the node where the task is running to see details about
the container for the task.
>**Tip**: If `helloworld` is running on a node other than your manager node,
you must ssh to that node.
@ -114,12 +121,12 @@ see the service container.
$docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a0b6c02868ca alpine:latest "ping docker.com" 12 minutes ago Up 12 minutes helloworld.1.1n6wif51j0w840udalgw6hphg
e609dde94e47 alpine:latest "ping docker.com" 3 minutes ago Up 3 minutes helloworld.1.8p1vev3fq5zm0mi8g0as41w35
```
## What's next?
Next, you can [change the scale](scale-service.md) for the service running in
the Swarm.
the swarm.
<p style="margin-bottom:300px">&nbsp;</p>

4
docs/swarm/swarm-tutorial/menu.md
View file

@ -11,11 +11,11 @@ weight=10
+++
<![end-metadata]-->
# Docker Swarm getting started tutorial
# Docker Engine swarm mode getting started tutorial
## TOC
- [Begin the tutorial](index.md) - Setup your environment to prepare
to build a Swarm.
to build a swarm.
<p style="margin-bottom:300px">&nbsp;</p>

43
docs/swarm/swarm-tutorial/rolling-update.md
View file

@ -14,20 +14,21 @@ weight=20
# Apply rolling updates to a service
In a previous step of the tutorial, you [scaled](scale-service.md) the number of
instances of a service. In this part of the tutorial, you deploy a new Redis
service and upgrade the service using rolling updates.
instances of a service. In this part of the tutorial, you deploy a service based
on the Redis 3.0.6 container image. Then you upgrade the service to use the
Redis 3.0.7 container image using rolling updates.
1. If you haven't already, open a terminal and ssh into the machine where you
run your manager node. For example, the tutorial uses a machine named
`manager1`.
2. Deploy Redis 3.0.6 to all nodes in the Swarm and configure
the swarm to update one node every 10 seconds:
2. Deploy Redis 3.0.6 to the swarm and configure the swarm to update one node
every 10 seconds:
```bash
$ docker service create --replicas 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
8m228injfrhdym2zvzhl9k3l0
0u6a4s31ybk7yw2wyvtikmu50
```
You configure the rolling update policy at service deployment time.
@ -42,13 +43,13 @@ the swarm to update one node every 10 seconds:
3. Inspect the `redis` service:
```
```bash
$ docker service inspect redis --pretty
ID: 75kcmhuf8mif4a07738wttmgl
ID: 0u6a4s31ybk7yw2wyvtikmu50
Name: redis
Mode: REPLICATED
Scale: 3
Replicas: 3
Placement:
Strategy: SPREAD
UpdateConfig:
@ -58,8 +59,8 @@ the swarm to update one node every 10 seconds:
Image: redis:3.0.6
```
4. Now you can update the container image for `redis`. Swarm applies the update
to nodes according to the `UpdateConfig` policy:
4. Now you can update the container image for `redis`. The swarm manager
applies the update to nodes according to the `UpdateConfig` policy:
```bash
$ docker service update --image redis:3.0.7 redis
@ -69,37 +70,37 @@ to nodes according to the `UpdateConfig` policy:
5. Run `docker service inspect --pretty redis` to see the new image in the
desired state:
```
```bash
docker service inspect --pretty redis
ID: 1yrcci9v8zj6cokua2eishlob
ID: 0u6a4s31ybk7yw2wyvtikmu50
Name: redis
Mode: REPLICATED
Scale: 3
Replicas: 3
Placement:
Strategy: SPREAD
UpdateConfig:
Parallelism: 1
Delay: 10s
ContainerSpec:
Image: redis:3.0.7
ContainerSpec:
Image: redis:3.0.7
```
6. Run `docker service tasks <TASK-ID>` to watch the rolling update:
```
```bash
$ docker service tasks redis
ID NAME SERVICE IMAGE DESIRED STATE LAST STATE NODE
5409nu4crb0smamziqwuug67u redis.1 redis redis:3.0.7 RUNNING RUNNING 21 seconds worker2
b8ezq58zugcg1trk8k7jrq9ym redis.2 redis redis:3.0.7 RUNNING RUNNING 1 seconds worker1
cgdcbipxnzx0y841vysiafb64 redis.3 redis redis:3.0.7 RUNNING RUNNING 11 seconds worker1
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
dos1zffgeofhagnve8w864fco redis.1 redis redis:3.0.7 Running 37 seconds Running worker1
9l3i4j85517skba5o7tn5m8g0 redis.2 redis redis:3.0.7 Running About a minute Running worker2
egiuiqpzrdbxks3wxgn8qib1g redis.3 redis redis:3.0.7 Running 48 seconds Running worker1
```
Before Swarm updates all of the tasks, you can see that some are running
`redis:3.0.6` while others are running `redis:3.0.7`. The output above shows
the state once the rolling updates are done. You can see that each instances
entered the `RUNNING` state in 10 second increments.
entered the `RUNNING` state in approximately 10 second increments.
Next, learn about how to [drain a node](drain-node.md) in the Swarm.

41
docs/swarm/swarm-tutorial/scale-service.md
View file

@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "Scale the service"
description = "Scale the service running in the Swarm"
keywords = ["tutorial, cluster management, swarm, scale"]
description = "Scale the service running in the swarm"
keywords = ["tutorial, cluster management, swarm mode, scale"]
advisory = "rc"
[menu.main]
identifier="swarm-tutorial-scale-service"
@ -11,29 +11,29 @@ weight=18
+++
<![end-metadata]-->
# Scale the service in the Swarm
# Scale the service in the swarm
Once you have [deployed a service](deploy-service.md) to a Swarm, you are ready
Once you have [deployed a service](deploy-service.md) to a swarm, you are ready
to use the Docker CLI to scale the number of service tasks in
the Swarm.
the swarm.
1. If you haven't already, open a terminal and ssh into the machine where you
run your manager node. For example, the tutorial uses a machine named
`manager1`.
2. Run the following command to change the desired state of the
service runing in the Swarm:
service running in the swarm:
```bash
$ docker service update --replicas <NUMBER-OF-TASKS> <SERVICE-ID>
$ docker service scale <SERVICE-ID>=<NUMBER-OF-TASKS>
```
The `--replicas` flag indicates the number of tasks you want in the new
desired state. For example:
For example:
```bash
$ docker service update --replicas 5 helloworld
helloworld
$ docker service scale helloworld=5
helloworld scaled to 5
```
3. Run `docker service tasks <SERVICE-ID>` to see the updated task list:
@ -41,17 +41,17 @@ service runing in the Swarm:
```
$ docker service tasks helloworld
ID NAME SERVICE IMAGE DESIRED STATE LAST STATE NODE
1n6wif51j0w840udalgw6hphg helloworld.1 helloworld alpine RUNNING RUNNING 2 minutes manager1
dfhsosk00wxfb7j0cazp3fmhy helloworld.2 helloworld alpine RUNNING RUNNING 15 seconds worker2
6cbedbeywo076zn54fnwc667a helloworld.3 helloworld alpine RUNNING RUNNING 15 seconds worker1
7w80cafrry7asls96lm2tmwkz helloworld.4 helloworld alpine RUNNING RUNNING 10 seconds worker1
bn67kh76crn6du22ve2enqg5j helloworld.5 helloworld alpine RUNNING RUNNING 10 seconds manager1
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
8p1vev3fq5zm0mi8g0as41w35 helloworld.1 helloworld alpine Running 7 minutes Running worker2
c7a7tcdq5s0uk3qr88mf8xco6 helloworld.2 helloworld alpine Running 24 seconds Running worker1
6crl09vdcalvtfehfh69ogfb1 helloworld.3 helloworld alpine Running 24 seconds Running worker1
auky6trawmdlcne8ad8phb0f1 helloworld.4 helloworld alpine Running 24 seconds Accepted manager1
ba19kca06l18zujfwxyc5lkyn helloworld.5 helloworld alpine Running 24 seconds Running worker2
```
You can see that Swarm has created 4 new tasks to scale to a total of 5
You can see that swarm has created 4 new tasks to scale to a total of 5
running instances of Alpine Linux. The tasks are distributed between the
three nodes of the Swarm. Two are running on `manager1`.
three nodes of the swarm. Two are running on `manager1`.
4. Run `docker ps` to see the containers running on the node where you're
connected. The following example shows the tasks running on `manager1`:
@ -60,8 +60,7 @@ connected. The following example shows the tasks running on `manager1`:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
910669d5e188 alpine:latest "ping docker.com" 10 seconds ago Up 10 seconds helloworld.5.bn67kh76crn6du22ve2enqg5j
a0b6c02868ca alpine:latest "ping docker.com" 2 minutes ago Up 2 minutes helloworld.1.1n6wif51j0w840udalgw6hphg
528d68040f95 alpine:latest "ping docker.com" About a minute ago Up About a minute helloworld.4.auky6trawmdlcne8ad8phb0f1
```
If you want to see the containers running on other nodes, you can ssh into