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

add tutorial

Browse source 
Signed-off-by: Charles Smith <charles.smith@docker.com>
This commit is contained in:
Charles Smith 2016-06-07 17:08:36 -07:00 • committed by Tonis Tiigi
parent 9acf97b72a
commit ea4fef2d87
13 changed files with 961 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

79
docs/swarm/index.md Normal file
View file

@ -0,0 +1,79 @@
<!--[metadata]>
+++
title = "Swarm overview"
description = "Docker Swarm overview"
keywords = ["docker, container, cluster, swarm"]
[menu.main]
identifier="swarm_overview"
parent="engine_swarm"
weight="1"
advisory = "rc"
+++
<![end-metadata]-->
# Docker Swarm overview
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.
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.
If you’re using a Docker version prior to `v1.12.0-rc1`, see [Docker
Swarm](https://docs.docker.com/swarm).
## Feature highlights
* **Cluster management integrated with Docker Engine:** Use the Docker Engine
CLI to create a Swarm of Docker Engines where you can deploy application
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.
* **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.
* **Desired state reconciliation:** Swarm constantly monitors the cluster state
and reconciles any differences between the actual state your expressed desired
state.
* **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.
* **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.
* **Load balancing:** Using Swarm, you can expose the ports for services to an
external load balancer. Internally, Swarm lets you specify how to distribute
service containers between nodes.
* **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.
## What's next?
* Learn Swarm [key concepts](key-concepts.md).
* Get started with the [Swarm tutorial](swarm-tutorial/index.md).
<p style="margin-bottom:300px">&nbsp;</p>

85
docs/swarm/key-concepts.md Normal file
View file

@ -0,0 +1,85 @@
<!--[metadata]>
+++
title = "Swarm key concepts"
description = "Introducing key concepts for Docker Swarm"
keywords = ["docker, container, cluster, swarm"]
[menu.main]
identifier="swarm-concepts"
parent="engine_swarm"
weight="2"
advisory = "rc"
+++
<![end-metadata]-->
# Docker Swarm 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.
## Swarm
**Docker Swarm** is the name for the cluster management and orchestration features
embedded in the Docker Engine.
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.
## Node
A **node** is an active instance of the Docker Engine 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.
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.
**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.
## 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 **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.
## Service types
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.
## 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.
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.
<p style="margin-bottom:300px">&nbsp;</p>

21
docs/swarm/menu.md Normal file
View file

@ -0,0 +1,21 @@
<!--[metadata]>
+++
title = "Manage a Swarm (1.12 RC)"
description = "How to use Docker Swarm to create and manage Docker Engine clusters"
keywords = [" docker, documentation, developer, "]
[menu.main]
identifier = "engine_swarm"
parent = "engine_use"
weight = 0
advisory = "rc"
+++
<![end-metadata]-->
## Use Docker Swarm to create and manage clusters of Docker Engine called Swarms
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)

64
docs/swarm/swarm-tutorial/add-nodes.md Normal file
View file

@ -0,0 +1,64 @@
<!--[metadata]>
+++
title = "Add nodes to the Swarm"
description = "Add nodes to the Swarm"
keywords = ["tutorial, cluster management, swarm"]
[menu.main]
identifier="add-nodes"
parent="swarm-tutorial"
weight=13
advisory = "rc"
+++
<![end-metadata]-->
# Add nodes to the Swarm
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 `docker swarm join MANAGER-IP:PORT` to create a worker node joined to the
existing Swarm. Replace MANAGER-IP address of the manager node and the port
where the manager listens.
In the tutorial, the following command joins `worker1` to the Swarm on `manager1`:
```
$ docker swarm join 192.168.99.100:2377
This node joined a Swarm as a worker.
```
3. Open a terminal and ssh into the machine where you want to run a second
worker node. This tutorial uses the name `worker2`.
4. Run `docker swarm join MANAGER-IP:PORT` to create a worker node joined to
the existing Swarm. Replace MANAGER-IP address of the manager node and the port
where the manager listens.
5. Open a terminal and ssh into the machine where the manager node runs and run
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
```
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.
## 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.
<p style="margin-bottom:300px">&nbsp;</p>

77
docs/swarm/swarm-tutorial/create-swarm.md Normal file
View file

@ -0,0 +1,77 @@
<!--[metadata]>
+++
title = "Create a Swarm"
description = "Initialize the Swarm"
keywords = ["tutorial, cluster management, swarm"]
[menu.main]
identifier="initialize-swarm"
parent="swarm-tutorial"
weight=12
advisory = "rc"
+++
<![end-metadata]-->
# 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
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 `docker swarm init --listen-addr MANAGER-IP:PORT` to create a new Swarm.
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.
```
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
the IP address.
3. Run `docker info` to view the current state of the Swarm:
```
$ docker info
Containers: 2
Running: 0
Paused: 0
Stopped: 2
...snip...
Swarm:
NodeID: 09fm6su6c24qn
IsManager: YES
Managers: 1
Nodes: 1
...snip...
```
4. Run the `docker node ls` command to view information about nodes:
```
$ docker node ls
ID NAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
09fm6su6c24q * 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.
## What's next?
In the next section of the tutorial, we'll [add two more nodes](add-nodes.md) to
the cluster.
<p style="margin-bottom:300px">&nbsp;</p>

44
docs/swarm/swarm-tutorial/delete-service.md Normal file
View file

@ -0,0 +1,44 @@
<!--[metadata]>
+++
title = "Delete the service"
description = "Remove the service on the Swarm"
keywords = ["tutorial, cluster management, swarm, service"]
[menu.main]
identifier="swarm-tutorial-delete-service"
parent="swarm-tutorial"
weight=19
advisory = "rc"
+++
<![end-metadata]-->
# 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.
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 `docker service remove helloworld` to remove the `helloworld` service.
```
$ 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:
```
$ docker service inspect helloworld
[]
Error: no such service or task: helloworld
```
## What's next?
In the next step of the tutorial, you set up a new service and and apply a
[rolling update](rolling-update.md).
<p style="margin-bottom:300px">&nbsp;</p>

50
docs/swarm/swarm-tutorial/deploy-service.md Normal file
View file

@ -0,0 +1,50 @@
<!--[metadata]>
+++
title = "Deploy a service"
description = "Deploy the application"
keywords = ["tutorial, cluster management, swarm"]
[menu.main]
identifier="deploy-application"
parent="swarm-tutorial"
weight=16
advisory = "rc"
+++
<![end-metadata]-->
# 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
is not a requirement to deploy a service.
1. 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 the following command:
```bash
$ docker service create --scale 1 --name helloworld alpine ping docker.com
2zs4helqu64f3k3iuwywbk49w
```
* The `docker service create` command creates the service.
* The `--name` flag names the service `helloworld`.
* The `--scale` flag specifies the desired state of 1 running instance.
* The arguments `alpine ping docker.com` define the service as an Alpine
Linux container that executes the command `ping docker.com`.
3. Run `docker service ls` to see the list of running services:
```
$ docker service ls
ID NAME SCALE IMAGE COMMAND
2zs4helqu64f helloworld 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).
<p style="margin-bottom:300px">&nbsp;</p>

129
docs/swarm/swarm-tutorial/drain-node.md Normal file
View file

@ -0,0 +1,129 @@
<!--[metadata]>
+++
title = "Drain a node"
description = "Drain nodes on the Swarm"
keywords = ["tutorial, cluster management, swarm, service, drain"]
[menu.main]
identifier="swarm-tutorial-drain-node"
parent="swarm-tutorial"
weight=21
+++
<![end-metadata]-->
# 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.
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
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
run your manager node. For example, the tutorial uses a machine named
`manager1`.
2. Verify that all your nodes are actively available.
```
$ 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
```
2. If you aren't still running the `redis` service from the [rolling
update](rolling-update.md) tutorial, start it now:
```bash
$ docker service create --scale 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
69uh57k8o03jtqj9uvmteodbb
```
3. Run `docker service tasks redis` to see how the Swarm manager assigned the
tasks to different nodes:
```
$ 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
```
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
had a task assigned to it:
```bash
docker node update --availability drain worker1
worker1
```
5. Inspect the node to check its availability:
```
$ docker node inspect --pretty worker1
ID: 1x2bldyhie1cj
Hostname: worker1
Status:
State: READY
Availability: DRAIN
...snip...
```
The drained node shows `Drain` for `AVAILABILITY`.
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
```
The Swarm manager maintains the desired state by ending the task on a node
with `Drain` availability and creating a new task on a node with `Active`
availability.
7. Run `docker node update --availability active NODE-ID` to return the drained
node to an active state:
```bash
$ docker node update --availability active worker1
worker1
```
8. Inspect the node to see the updated state:
```
$ docker node inspect --pretty worker1
ID: 1x2bldyhie1cj
Hostname: worker1
Status:
State: READY
Availability: ACTIVE
...snip...
```
When you set the node back to `Active` availability, it can receive new tasks:
* during a service update to scale up
* during a rolling update
* when you set another node to `Drain` availability
* when a task fails on another active node
## What's next?
The next topic in the tutorial introduces volumes.
<p style="margin-bottom:300px">&nbsp;</p>

87
docs/swarm/swarm-tutorial/index.md Normal file
View file

@ -0,0 +1,87 @@
<!--[metadata]>
+++
title = "Set up for the tutorial"
description = "Getting Started tutorial for Docker Swarm"
keywords = ["tutorial, cluster management, swarm"]
[menu.main]
identifier="tutorial-setup"
parent="swarm-tutorial"
weight=11
advisory = "rc"
+++
<![end-metadata]-->
# Getting Started with Docker Swarm
This tutorial introduces you to the key features of Docker Swarm. It guides you
through the following activities:
* 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
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
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)
* [Docker Engine 1.12 or later installed](#docker-engine-1-12-or-later)
* [the IP address of the manager machine](#the-ip-address-of-the-manager-machine)
* [open ports between the hosts](#open-ports-between-the-hosts)
### Three networked host machines
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:
* manager1
* worker1
* worker2
### 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.
Verify that the Docker Engine daemon is running on each of the machines.
<!-- See the following options to install:
* [Install Docker Engine](../../installation/index.md).
* [Example: Manual install on cloud provider](../../installation/cloud/cloud-ex-aws.md).
-->
### 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.
>**Tip**: You can run `ifconfig` on Linux or Mac OSX to see a list of the
available network interfaces.
The tutorial uses `manager1` : `192.168.99.100`.
### Open ports between the hosts
* **TCP port 2377** for cluster management communications
* **TCP** and **UDP port 7946** for communication among nodes
* **TCP** and **UDP port 4789** for overlay network traffic
>**Tip**: Docker recommends that every node in the cluster be on the same layer
3 (IP) subnet with all traffic permitted between nodes.
## What's next?
After you have set up your environment, you're ready to [create a Swarm](create-swarm.md).
<p style="margin-bottom:300px">&nbsp;</p>

124
docs/swarm/swarm-tutorial/inspect-service.md Normal file
View file

@ -0,0 +1,124 @@
<!--[metadata]>
+++
title = "Inspect the service"
description = "Inspect the application"
keywords = ["tutorial, cluster management, swarm"]
[menu.main]
identifier="inspect-application"
parent="swarm-tutorial"
weight=17
advisory = "rc"
+++
<![end-metadata]-->
# 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.
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 `docker service inspect --pretty SERVICE-ID` to display the details about
a service in an easily readable format.
To see the details on the `helloworld` service:
```
$ docker service inspect --pretty helloworld
ID: 2zs4helqu64f3k3iuwywbk49w
Name: helloworld
Mode: REPLICATED
Scale: 1
Placement:
Strategy: SPREAD
UpateConfig:
Parallelism: 1
ContainerSpec:
Image: alpine
Command: ping docker.com
```
>**Tip**: To return the service details in json format, run the same command
without the `--pretty` flag.
```
$ docker service inspect helloworld
[
{
"ID": "2zs4helqu64f3k3iuwywbk49w",
"Version": {
"Index": 16264
},
"CreatedAt": "2016-06-06T17:41:11.509146705Z",
"UpdatedAt": "2016-06-06T17:41:11.510426385Z",
"Spec": {
"Name": "helloworld",
"ContainerSpec": {
"Image": "alpine",
"Command": [
"ping",
"docker.com"
],
"Resources": {
"Limits": {},
"Reservations": {}
}
},
"Mode": {
"Replicated": {
"Instances": 1
}
},
"RestartPolicy": {},
"Placement": {},
"UpdateConfig": {
"Parallelism": 1
},
"EndpointSpec": {}
},
"Endpoint": {
"Spec": {}
}
}
]
```
4. Run `docker service tasks SERVICE-ID` to see which nodes are running the
service:
```
$ docker service tasks helloworld
ID NAME SERVICE IMAGE DESIRED STATE LAST STATE NODE
1n6wif51j0w840udalgw6hphg helloworld.1 helloworld alpine RUNNING RUNNING 19 minutes manager1
```
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.
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.
>**Tip**: If `helloworld` is running on a node other than your manager node,
you must ssh to that node.
```bash
$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
```
## What's next?
Next, you can [change the scale](scale-service.md) for the service running in
the Swarm.
<p style="margin-bottom:300px">&nbsp;</p>

21
docs/swarm/swarm-tutorial/menu.md Normal file
View file

@ -0,0 +1,21 @@
<!--[metadata]>
+++
title = "Get started with Swarm"
description = "Getting started tutorial for Docker Swarm"
keywords = ["cluster, swarm, tutorial"]
[menu.main]
identifier="swarm-tutorial"
parent="engine_swarm"
weight=10
advisory = "rc"
+++
<![end-metadata]-->
# Docker Swarm getting started tutorial
## TOC
- [Begin the tutorial](index.md) - Setup your environment to prepare
to build a Swarm.
<p style="margin-bottom:300px">&nbsp;</p>

105
docs/swarm/swarm-tutorial/rolling-update.md Normal file
View file

@ -0,0 +1,105 @@
<!--[metadata]>
+++
title = "Apply rolling updates"
description = "Apply rolling updates to a service on the Swarm"
keywords = ["tutorial, cluster management, swarm, service, rolling-update"]
[menu.main]
identifier="swarm-tutorial-rolling-update"
parent="swarm-tutorial"
weight=20
advisory = "rc"
+++
<![end-metadata]-->
# 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.
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:
```bash
$ docker service create --scale 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
8m228injfrhdym2zvzhl9k3l0
```
You configure the rolling update policy at service deployment time.
The `--update-parallelism` flag configures the number of service tasks
to update simultaneously.
The `--update-delay` flag configures the time delay between updates to
a service task or sets of tasks. You can describe the time `T` in the number
of seconds `Ts`, minutes `Tm`, or hours `Th`. So `10m` indicates a 10 minute
delay.
3. Inspect the `redis` service:
```
$ docker service inspect redis --pretty
ID: 75kcmhuf8mif4a07738wttmgl
Name: redis
Mode: REPLICATED
Scale: 3
Placement:
Strategy: SPREAD
UpateConfig:
Parallelism: 1
Delay: 10s
ContainerSpec:
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:
```bash
$ docker service update --image redis:3.0.7 redis
redis
```
5. Run `docker service inspect --pretty redis` to see the new image in the
desired state:
```
docker service inspect --pretty redis
ID: 1yrcci9v8zj6cokua2eishlob
Name: redis
Mode: REPLICATED
Scale: 3
Placement:
Strategy: SPREAD
UpdateConfig:
Parallelism: 1
Delay: 10s
ContainerSpec:
Image: redis:3.0.7
```
6. Run `docker service tasks TASK-ID` to watch the rolling update:
```
$ 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
```
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.
Next, learn about how to [drain a node](drain-node.md) in the Swarm.
<p style="margin-bottom:300px">&nbsp;</p>

75
docs/swarm/swarm-tutorial/scale-service.md Normal file
View file

@ -0,0 +1,75 @@
<!--[metadata]>
+++
title = "Scale the service"
description = "Scale the service running in the Swarm"
keywords = ["tutorial, cluster management, swarm, scale"]
[menu.main]
identifier="swarm-tutorial-scale-service"
parent="swarm-tutorial"
weight=18
advisory = "rc"
+++
<![end-metadata]-->
# Scale the service in the Swarm
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.
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:
```
$ docker service update --scale NUMBER-OF-TASKS SERVICE-ID
```
The `--scale` flag indicates the number of tasks you want in the new desired
state. For example:
```
$ docker service update --scale 5 helloworld
helloworld
```
3. Run `docker service tasks SERVICE-ID` to see the updated task list:
```
$ 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
```
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`.
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`:
```
$ 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
```
If you want to see the containers running on other nodes, you can ssh into
those nodes and run the `docker ps` command.
## What's next?
At this point in the tutorial, you're finished with the `helloworld` service.
The next step shows how to [delete the service](delete-service.md).
<p style="margin-bottom:300px">&nbsp;</p>