diff --git a/docs/swarm/index.md b/docs/swarm/index.md index ebf3168a33..7514f329a8 100644 --- a/docs/swarm/index.md +++ b/docs/swarm/index.md @@ -1,7 +1,7 @@ -# 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).

 

diff --git a/docs/swarm/key-concepts.md b/docs/swarm/key-concepts.md index 814e2be17f..55fc35c82c 100644 --- a/docs/swarm/key-concepts.md +++ b/docs/swarm/key-concepts.md @@ -1,86 +1,93 @@ -# 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).

 

diff --git a/docs/swarm/menu.md b/docs/swarm/menu.md index 7864943325..e74c724f7b 100644 --- a/docs/swarm/menu.md +++ b/docs/swarm/menu.md @@ -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) diff --git a/docs/swarm/swarm-tutorial/add-nodes.md b/docs/swarm/swarm-tutorial/add-nodes.md index e052879ec0..d6da80cd4a 100644 --- a/docs/swarm/swarm-tutorial/add-nodes.md +++ b/docs/swarm/swarm-tutorial/add-nodes.md @@ -1,7 +1,7 @@ -# 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 : @@ -29,7 +29,7 @@ the existing Swarm: Replace `` with the address of the manager node and `` 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.

 

diff --git a/docs/swarm/swarm-tutorial/create-swarm.md b/docs/swarm/swarm-tutorial/create-swarm.md index 6f82a4de18..d57c7e07f4 100644 --- a/docs/swarm/swarm-tutorial/create-swarm.md +++ b/docs/swarm/swarm-tutorial/create-swarm.md @@ -1,8 +1,8 @@ -# 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 : ``` - 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? diff --git a/docs/swarm/swarm-tutorial/delete-service.md b/docs/swarm/swarm-tutorial/delete-service.md index 8e74ef84f6..ee1e1c805a 100644 --- a/docs/swarm/swarm-tutorial/delete-service.md +++ b/docs/swarm/swarm-tutorial/delete-service.md @@ -1,7 +1,7 @@ -# 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 ` to veriy that Swarm removed the -service. The CLI returns a message that the service is not found: +3. Run `docker service inspect ` to veriy that the swarm manager +removed the service. The CLI returns a message that the service is not found: ``` $ docker service inspect helloworld diff --git a/docs/swarm/swarm-tutorial/deploy-service.md b/docs/swarm/swarm-tutorial/deploy-service.md index f6f0e08932..81d2cb5312 100644 --- a/docs/swarm/swarm-tutorial/deploy-service.md +++ b/docs/swarm/swarm-tutorial/deploy-service.md @@ -1,8 +1,8 @@ -# 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).

 

diff --git a/docs/swarm/swarm-tutorial/drain-node.md b/docs/swarm/swarm-tutorial/drain-node.md index 8b8fb4ff03..e1984ca3dd 100644 --- a/docs/swarm/swarm-tutorial/drain-node.md +++ b/docs/swarm/swarm-tutorial/drain-node.md @@ -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 +++ -# 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 ` 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... ``` diff --git a/docs/swarm/swarm-tutorial/index.md b/docs/swarm/swarm-tutorial/index.md index 366a574b46..18b3d76ed4 100644 --- a/docs/swarm/swarm-tutorial/index.md +++ b/docs/swarm/swarm-tutorial/index.md @@ -1,8 +1,8 @@ -# 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).

 

diff --git a/docs/swarm/swarm-tutorial/inspect-service.md b/docs/swarm/swarm-tutorial/inspect-service.md index c0ca3f5c1a..89064cb89b 100644 --- a/docs/swarm/swarm-tutorial/inspect-service.md +++ b/docs/swarm/swarm-tutorial/inspect-service.md @@ -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 +++ -# 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.

 

diff --git a/docs/swarm/swarm-tutorial/menu.md b/docs/swarm/swarm-tutorial/menu.md index dd3721ef4e..ca37de4d41 100644 --- a/docs/swarm/swarm-tutorial/menu.md +++ b/docs/swarm/swarm-tutorial/menu.md @@ -11,11 +11,11 @@ weight=10 +++ -# 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.

 

diff --git a/docs/swarm/swarm-tutorial/rolling-update.md b/docs/swarm/swarm-tutorial/rolling-update.md index a7b072a875..2cf1eb2017 100644 --- a/docs/swarm/swarm-tutorial/rolling-update.md +++ b/docs/swarm/swarm-tutorial/rolling-update.md @@ -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 ` 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. diff --git a/docs/swarm/swarm-tutorial/scale-service.md b/docs/swarm/swarm-tutorial/scale-service.md index 2228e2eb00..42bc813178 100644 --- a/docs/swarm/swarm-tutorial/scale-service.md +++ b/docs/swarm/swarm-tutorial/scale-service.md @@ -1,8 +1,8 @@ -# 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 + $ docker service scale = ``` - 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 ` 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