diff --git a/docs/swarm/index.md b/docs/swarm/index.md new file mode 100644 index 0000000000..abfd033502 --- /dev/null +++ b/docs/swarm/index.md @@ -0,0 +1,79 @@ + +# 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). + +

 

diff --git a/docs/swarm/key-concepts.md b/docs/swarm/key-concepts.md new file mode 100644 index 0000000000..e63c13eba0 --- /dev/null +++ b/docs/swarm/key-concepts.md @@ -0,0 +1,85 @@ + +# 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. + +

 

diff --git a/docs/swarm/menu.md b/docs/swarm/menu.md new file mode 100644 index 0000000000..df43027f2f --- /dev/null +++ b/docs/swarm/menu.md @@ -0,0 +1,21 @@ + + + +## 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) diff --git a/docs/swarm/swarm-tutorial/add-nodes.md b/docs/swarm/swarm-tutorial/add-nodes.md new file mode 100644 index 0000000000..9adb57f626 --- /dev/null +++ b/docs/swarm/swarm-tutorial/add-nodes.md @@ -0,0 +1,64 @@ + + +# 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. + +

 

diff --git a/docs/swarm/swarm-tutorial/create-swarm.md b/docs/swarm/swarm-tutorial/create-swarm.md new file mode 100644 index 0000000000..1e0a9fc220 --- /dev/null +++ b/docs/swarm/swarm-tutorial/create-swarm.md @@ -0,0 +1,77 @@ + + +# 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. + + +

 

diff --git a/docs/swarm/swarm-tutorial/delete-service.md b/docs/swarm/swarm-tutorial/delete-service.md new file mode 100644 index 0000000000..63c679b410 --- /dev/null +++ b/docs/swarm/swarm-tutorial/delete-service.md @@ -0,0 +1,44 @@ + + +# 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). + +

 

diff --git a/docs/swarm/swarm-tutorial/deploy-service.md b/docs/swarm/swarm-tutorial/deploy-service.md new file mode 100644 index 0000000000..0b24e0057b --- /dev/null +++ b/docs/swarm/swarm-tutorial/deploy-service.md @@ -0,0 +1,50 @@ + + +# 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). + +

 

diff --git a/docs/swarm/swarm-tutorial/drain-node.md b/docs/swarm/swarm-tutorial/drain-node.md new file mode 100644 index 0000000000..49bb81165e --- /dev/null +++ b/docs/swarm/swarm-tutorial/drain-node.md @@ -0,0 +1,129 @@ + + +# 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. + +

 

diff --git a/docs/swarm/swarm-tutorial/index.md b/docs/swarm/swarm-tutorial/index.md new file mode 100644 index 0000000000..4d4fdb07b9 --- /dev/null +++ b/docs/swarm/swarm-tutorial/index.md @@ -0,0 +1,87 @@ + + +# 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. + + + +### 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). + +

 

diff --git a/docs/swarm/swarm-tutorial/inspect-service.md b/docs/swarm/swarm-tutorial/inspect-service.md new file mode 100644 index 0000000000..8e4e3af9f9 --- /dev/null +++ b/docs/swarm/swarm-tutorial/inspect-service.md @@ -0,0 +1,124 @@ + + +# 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. + +

 

diff --git a/docs/swarm/swarm-tutorial/menu.md b/docs/swarm/swarm-tutorial/menu.md new file mode 100644 index 0000000000..aec86ae87d --- /dev/null +++ b/docs/swarm/swarm-tutorial/menu.md @@ -0,0 +1,21 @@ + + +# Docker Swarm getting started tutorial + +## TOC + +- [Begin the tutorial](index.md) - Setup your environment to prepare + to build a Swarm. + +

 

diff --git a/docs/swarm/swarm-tutorial/rolling-update.md b/docs/swarm/swarm-tutorial/rolling-update.md new file mode 100644 index 0000000000..20cb13488b --- /dev/null +++ b/docs/swarm/swarm-tutorial/rolling-update.md @@ -0,0 +1,105 @@ + + +# 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. + +

 

diff --git a/docs/swarm/swarm-tutorial/scale-service.md b/docs/swarm/swarm-tutorial/scale-service.md new file mode 100644 index 0000000000..5be6ddc48b --- /dev/null +++ b/docs/swarm/swarm-tutorial/scale-service.md @@ -0,0 +1,75 @@ + + +# 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). + +