New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Swarm tutorial documentation #23364

Merged
merged 1 commit into from Jun 14, 2016

Conversation

Projects
None yet
10 participants
@sfsmithcha
Contributor

sfsmithcha commented Jun 8, 2016

Add Swarm tutorial documentation.

Signed-off-by: Charles Smith charles.smith@docker.com

@icecrime icecrime changed the title from add tutorial to Add Swarm tutorial documentation Jun 8, 2016

@icecrime icecrime added this to the 1.12.0 milestone Jun 8, 2016

@SvenDowideit

This comment has been minimized.

Show comment
Hide comment
@SvenDowideit

SvenDowideit Jun 8, 2016

Contributor

the checker doesn't like docs/swarm/swarm-tutorial/delete-service.md - it looks like an empty file.

please add at least some frontmatter :)

Contributor

SvenDowideit commented Jun 8, 2016

the checker doesn't like docs/swarm/swarm-tutorial/delete-service.md - it looks like an empty file.

please add at least some frontmatter :)

Show outdated Hide outdated docs/swarm/swarm-tutorial/add-nodes.md
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>

This comment has been minimized.

@thaJeztah

thaJeztah Jun 8, 2016

Member

Is this needed? Or is this to prevent the bottom "wave" from overlapping the content? Perhaps we can address this somehow in a general style

@thaJeztah

thaJeztah Jun 8, 2016

Member

Is this needed? Or is this to prevent the bottom "wave" from overlapping the content? Perhaps we can address this somehow in a general style

@thaJeztah

This comment has been minimized.

Show comment
Hide comment
@thaJeztah

thaJeztah Jun 8, 2016

Member

Could you wrap to 80 chars as well?

Member

thaJeztah commented Jun 8, 2016

Could you wrap to 80 chars as well?

Show outdated Hide outdated docs/swarm/index.md
weight="1"
+++
<![end-metadata]-->
# Docker Swarm overview #

This comment has been minimized.

@thaJeztah

thaJeztah Jun 8, 2016

Member

Hm did that plugin add the trailing #?

@thaJeztah

thaJeztah Jun 8, 2016

Member

Hm did that plugin add the trailing #?

Show outdated Hide outdated docs/swarm/key-concepts.md
A **service** is the definition of how to run the various tasks that make up
your application. For example, you may want to run a Redis service in your
Swarm.

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

This part is a little confusing to me. How is a service related to a Docker image? In Cloud a "service" is one or more containers of the same image. It might be worth briefly touching on this relationship.

@sanscontext

sanscontext Jun 8, 2016

This part is a little confusing to me. How is a service related to a Docker image? In Cloud a "service" is one or more containers of the same image. It might be worth briefly touching on this relationship.

Show outdated Hide outdated docs/swarm/key-concepts.md
### Scheduling
Docker Swarm allows you to schedule service on nodes in the Swarm in the

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

a service? services?

@sanscontext

sanscontext Jun 8, 2016

a service? services?

Show outdated Hide outdated docs/swarm/key-concepts.md
**Service scheduling** distributes tasks among nodes for long-running,
persistent services.
**Fill scheduling** runs tasks on every available node.

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

This part is a little unclear - does service scheduling only distribute tasks among specific nodes? Does fill scheduling do something special before running tasks on every node? How do these two relate/differ?

@sanscontext

sanscontext Jun 8, 2016

This part is a little unclear - does service scheduling only distribute tasks among specific nodes? Does fill scheduling do something special before running tasks on every node? How do these two relate/differ?

This comment has been minimized.

@aluzzardi

aluzzardi Jun 9, 2016

Contributor

This should be "global services"

@aluzzardi

aluzzardi Jun 9, 2016

Contributor

This should be "global services"

This comment has been minimized.

@sfsmithcha

sfsmithcha Jun 9, 2016

Contributor

@aluzzardi is this accurate:

"Global services scheculing distributes tasks among the number of nodes according to the the desired state for long-running, persistent services."

So the answer to @sanscontext 's question is that Replicated services run on all nodes in the Swarm regardless of the desired state. Global services only run on the number of nodes according to the desired state.

@sfsmithcha

sfsmithcha Jun 9, 2016

Contributor

@aluzzardi is this accurate:

"Global services scheculing distributes tasks among the number of nodes according to the the desired state for long-running, persistent services."

So the answer to @sanscontext 's question is that Replicated services run on all nodes in the Swarm regardless of the desired state. Global services only run on the number of nodes according to the desired state.

Show outdated Hide outdated docs/swarm/key-concepts.md
following ways:
**Service scheduling** distributes tasks among nodes for long-running,
persistent services.

This comment has been minimized.

@aaronlehmann

aaronlehmann Jun 8, 2016

Contributor

Should this be "replicated scheduling"? cc @dongluochen

@aaronlehmann

aaronlehmann Jun 8, 2016

Contributor

Should this be "replicated scheduling"? cc @dongluochen

This comment has been minimized.

@aluzzardi

aluzzardi Jun 9, 2016

Contributor

This should be "replicated services"

@aluzzardi

aluzzardi Jun 9, 2016

Contributor

This should be "replicated services"

Show outdated Hide outdated docs/swarm/swarm-tutorial/tutorial-setup.md
@@ -0,0 +1,80 @@
<!--[metadata]>
+++
title = "Setup for the tutorial"

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

setup -> "set up" so we match the verb-first page names.

@sanscontext

sanscontext Jun 8, 2016

setup -> "set up" so we match the verb-first page names.

Show outdated Hide outdated docs/swarm/swarm-tutorial/tutorial-setup.md
inet6 fe80::d8:f5ff:fe48:cabb prefixlen 64 scopeid 0x20<link>
...snip...
```

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

And then what? When I run ifconfig I get a bunch of output I'm not sure how to parse. Am I looking for eth0 ? Am I looking for something else? Am I doing this for each of the three networked machines?

@sanscontext

sanscontext Jun 8, 2016

And then what? When I run ifconfig I get a bunch of output I'm not sure how to parse. Am I looking for eth0 ? Am I looking for something else? Am I doing this for each of the three networked machines?

Show outdated Hide outdated docs/swarm/swarm-tutorial/tutorial-setup.md
This tutorial uses the following host names and ip addresses :
* `manager1` : `192.168.99.100`
* `worker1` : `192.168.99.102`
* `worker2` : `192.168.99.100`

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

I read that a manager can also be a worker, but is that something we want to explain here? Otherwise it looks like a typo and one of our IPs is off by one.

@sanscontext

sanscontext Jun 8, 2016

I read that a manager can also be a worker, but is that something we want to explain here? Otherwise it looks like a typo and one of our IPs is off by one.

Show outdated Hide outdated docs/swarm/swarm-tutorial/tutorial-setup.md
```
For the manager node, the ip address serves as the VXLAN tunnel endpoint
(VTEP) for the Swarm.

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

This is a lot of acronyms. Expand and/or explain?

@sanscontext

sanscontext Jun 8, 2016

This is a lot of acronyms. Expand and/or explain?

Show outdated Hide outdated docs/swarm/swarm-tutorial/tutorial-setup.md
* `worker2` : `192.168.99.100`
* Docker recommends that every node in the cluster be on the same L3 subnet with

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

This is a bit jargony. Expand/explain what an L3 subnet is?

@sanscontext

sanscontext Jun 8, 2016

This is a bit jargony. Expand/explain what an L3 subnet is?

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

Actually, I might reverse these two - assume that they have all ports blocked and that they have to open these minimal ones, but mention (maybe as a Tip) that we recommend all traffic be permitted.

@sanscontext

sanscontext Jun 8, 2016

Actually, I might reverse these two - assume that they have all ports blocked and that they have to open these minimal ones, but mention (maybe as a Tip) that we recommend all traffic be permitted.

Show outdated Hide outdated docs/swarm/swarm-tutorial/tutorial-setup.md
* **TCP** and **UDP port 7946** for communication among nodes
* **TCP** and **UDP port 4789** for overlay network traffic
After you have setup your environment, you're ready to [create a Swarm](create-swarm.md).

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

I actually missed this reading it live in my instance. Maybe add an H2 that says "What's next?"

@sanscontext

sanscontext Jun 8, 2016

I actually missed this reading it live in my instance. Maybe add an H2 that says "What's next?"

Show outdated Hide outdated docs/swarm/swarm-tutorial/create-swarm.md
## Create a Swarm
After you install Docker on your networked machines and start the Docker Engine

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

This seems a bit weird to have prereqs here in prose. Let's make sure we explicitly tell them to start Docker Engine on the nodes in the previous file, and then we can just recap the prereqs here as a short bullet list.

@sanscontext

sanscontext Jun 8, 2016

This seems a bit weird to have prereqs here in prose. Let's make sure we explicitly tell them to start Docker Engine on the nodes in the previous file, and then we can just recap the prereqs here as a short bullet list.

This comment has been minimized.

@sfsmithcha

sfsmithcha Jun 8, 2016

Contributor

@sanscontext : Maybe so that we don't have the prereqs in a 3rd list , we can say "After you finish the tutorial setup?"

@sfsmithcha

sfsmithcha Jun 8, 2016

Contributor

@sanscontext : Maybe so that we don't have the prereqs in a 3rd list , we can say "After you finish the tutorial setup?"

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

I think that's totally reasonable. (But yeah, we do have to tell them to make sure Engine is running. Probably as part of the prereqs)

@sanscontext

sanscontext Jun 8, 2016

I think that's totally reasonable. (But yeah, we do have to tell them to make sure Engine is running. Probably as part of the prereqs)

Show outdated Hide outdated docs/swarm/swarm-tutorial/create-swarm.md
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. To create a new Swarm, run the following command:

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

I'd make this imperative so you can combine the follow-on into one line:
"Create a swarm and initialize a new node by running command."

@sanscontext

sanscontext Jun 8, 2016

I'd make this imperative so you can combine the follow-on into one line:
"Create a swarm and initialize a new node by running command."

Show outdated Hide outdated docs/swarm/swarm-tutorial/add-nodes.md
3. Open a terminal and ssh into the machine where the manager node runs and run
the `docker node ls` command to see the new worker node:
```bashtext

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

This cue is making it render ignoring the code block frame on my machine. Not your fault, but weird nonetheless.

@sanscontext

sanscontext Jun 8, 2016

This cue is making it render ignoring the code block frame on my machine. Not your fault, but weird nonetheless.

This comment has been minimized.

@sfsmithcha

sfsmithcha Jun 9, 2016

Contributor

@sanscontext , will render properly with updated skin. cue is to prevent it from mangling the font color (which might be less of an issue now the column title doesn't have an apostrophe.

@sfsmithcha

sfsmithcha Jun 9, 2016

Contributor

@sanscontext , will render properly with updated skin. cue is to prevent it from mangling the font color (which might be less of an issue now the column title doesn't have an apostrophe.

Show outdated Hide outdated docs/swarm/swarm-tutorial/add-nodes.md
Swarm management commands like `docker node ls` only work on manager nodes.
4. Repeat these steps for your your second worker node: `worker2`. When you run
`docker node ls` from your manager node, you can see all three nodes--one

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

I would split these. For step 4, reiterate the command. Then make a separate verification step where you look at the swarm membership.

@sanscontext

sanscontext Jun 8, 2016

I would split these. For step 4, reiterate the command. Then make a separate verification step where you look at the swarm membership.

Show outdated Hide outdated docs/swarm/swarm-tutorial/deploy-service.md
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. Using the `docker service create` command, you can do the following:

This comment has been minimized.

@sanscontext

sanscontext Jun 8, 2016

You can do these things, but which of them should we be doing for this tutorial? If this is purely informational, we should consider either removing it, or reworking it so that you demonstrate it in the tutorial.

@sanscontext

sanscontext Jun 8, 2016

You can do these things, but which of them should we be doing for this tutorial? If this is purely informational, we should consider either removing it, or reworking it so that you demonstrate it in the tutorial.

Show outdated Hide outdated docs/swarm/key-concepts.md
schedule a Redis container to run on a worker node.
### Scheduling

This comment has been minimized.

@aluzzardi

aluzzardi Jun 9, 2016

Contributor

Not sure if this should be phrased as "scheduling" or simply as "service types"

@aluzzardi

aluzzardi Jun 9, 2016

Contributor

Not sure if this should be phrased as "scheduling" or simply as "service types"

This comment has been minimized.

@sfsmithcha

sfsmithcha Jun 9, 2016

Contributor

@aluzzardi propposed update:

"""

Service types

Docker Swarm schedules service tasks on nodes in the Swarm based upon the service type:

Swarm distributes tasks for global services among nodes according to the number in the desired state for long-running, persistent services.

Swarm schedules tasks on every available node for replicated services.
"""

@sfsmithcha

sfsmithcha Jun 9, 2016

Contributor

@aluzzardi propposed update:

"""

Service types

Docker Swarm schedules service tasks on nodes in the Swarm based upon the service type:

Swarm distributes tasks for global services among nodes according to the number in the desired state for long-running, persistent services.

Swarm schedules tasks on every available node for replicated services.
"""

@HackToday

This comment has been minimized.

Show comment
Hide comment
@HackToday

HackToday Jun 11, 2016

Contributor

Good to know to have swarmkit related docs here, would be helpful to understand what it relation between swarm and swarmkit and engine etc. As introduced many tools in docker world.

Contributor

HackToday commented Jun 11, 2016

Good to know to have swarmkit related docs here, would be helpful to understand what it relation between swarm and swarmkit and engine etc. As introduced many tools in docker world.

Show outdated Hide outdated docs/swarm/swarm-tutorial/add-nodes.md
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:
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

can you remove the bashtext? Looks like it doesn't really render properly;

screen shot 2016-06-13 at 15 57 31

@thaJeztah

thaJeztah Jun 13, 2016

Member

can you remove the bashtext? Looks like it doesn't really render properly;

screen shot 2016-06-13 at 15 57 31

This comment has been minimized.

@sfsmithcha

sfsmithcha Jun 13, 2016

Contributor

that is the old css, think it is ok in the new one. however, this a suggestion from @SvenDowideit to solve a problem where an apostrophe in the column title causes everything after it to print red. that problem has gone away so setting to bash appears to work.

@sfsmithcha

sfsmithcha Jun 13, 2016

Contributor

that is the old css, think it is ok in the new one. however, this a suggestion from @SvenDowideit to solve a problem where an apostrophe in the column title causes everything after it to print red. that problem has gone away so setting to bash appears to work.

Show outdated Hide outdated docs/swarm/swarm-tutorial/deploy-service.md
2. Run the the following command:
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

same here (bashtext)

@thaJeztah

thaJeztah Jun 13, 2016

Member

same here (bashtext)

Show outdated Hide outdated docs/swarm/swarm-tutorial/inspect-service.md
```
>**Tip**: To return the service details in json format, run the same command
without the `--pretty` flag.

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

Perhaps the Tip needs to be indented as well, because the code block below now shows the "fences" (backticks);

screen shot 2016-06-13 at 15 59 17

@thaJeztah

thaJeztah Jun 13, 2016

Member

Perhaps the Tip needs to be indented as well, because the code block below now shows the "fences" (backticks);

screen shot 2016-06-13 at 15 59 17

Show outdated Hide outdated docs/swarm/swarm-tutorial/inspect-service.md
>**Tip**: If `helloworld` is running on a node other than your manager node, you
must ssh to that node.
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

Looks like this line is indented too much; either keep the indent and remove the "fence", or reduce indentation with four spaces. Also, please remove the bashtext code-hint;

screen shot 2016-06-13 at 16 01 27

@thaJeztah

thaJeztah Jun 13, 2016

Member

Looks like this line is indented too much; either keep the indent and remove the "fence", or reduce indentation with four spaces. Also, please remove the bashtext code-hint;

screen shot 2016-06-13 at 16 01 27

Show outdated Hide outdated docs/swarm/swarm-tutorial/scale-service.md
2. Run the following command to change the desired state of the
service runing in the Swarm:
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

can you remove the bashtext here

@thaJeztah

thaJeztah Jun 13, 2016

Member

can you remove the bashtext here

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

should be bash for this example

@thaJeztah

thaJeztah Jun 13, 2016

Member

should be bash for this example

Show outdated Hide outdated docs/swarm/swarm-tutorial/scale-service.md
The `--scale` flag indicates the number of tasks you want in the new desired
state. For example:
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

same here

@thaJeztah

thaJeztah Jun 13, 2016

Member

same here

Show outdated Hide outdated docs/swarm/swarm-tutorial/rolling-update.md
2. Deploy Redis 3.0.6 to all nodes in the Swarm and configure
the swarm to update one node every 10 seconds:
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

same here (bashtext)

@thaJeztah

thaJeztah Jun 13, 2016

Member

same here (bashtext)

Show outdated Hide outdated docs/swarm/swarm-tutorial/rolling-update.md
4. Now you can update the container image for `redis`. Swarm applies the update
to nodes according to the `UpdateConfig` policy:
```bashtext

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

and here

@thaJeztah

thaJeztah Jun 13, 2016

Member

and here

Show outdated Hide outdated docs/swarm/swarm-tutorial/add-nodes.md
+++
<![end-metadata]-->
## Add nodes to the Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/create-swarm.md
+++
<![end-metadata]-->
## Create a Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/delete-service.md
+++
<![end-metadata]-->
## Delete the service running on the Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/deploy-service.md
+++
<![end-metadata]-->
## Deploy a service to the Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/drain-node.md
+++
<![end-metadata]-->
## Drain a node on the Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/index.md
+++
<![end-metadata]-->
## Getting Started with Docker Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/inspect-service.md
+++
<![end-metadata]-->
## Inspect a service on the Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/rolling-update.md
+++
<![end-metadata]-->
## Apply rolling updates to a service

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/scale-service.md
+++
<![end-metadata]-->
## Scale the service in the Swarm

This comment has been minimized.

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

@thaJeztah

thaJeztah Jun 13, 2016

Member

This should be a H1 (#)

Show outdated Hide outdated docs/swarm/swarm-tutorial/add-nodes.md
Swarm management commands like `docker node ls` only work on manager nodes.
4. Repeat these steps for your your second worker node: `worker2`. When you run

This comment has been minimized.

@mlaventure

mlaventure Jun 13, 2016

Contributor

There's an extra your here.

@mlaventure

mlaventure Jun 13, 2016

Contributor

There's an extra your here.

add tutorial
Signed-off-by: Charles Smith <charles.smith@docker.com>
@icecrime

This comment has been minimized.

Show comment
Hide comment
@icecrime

icecrime Jun 14, 2016

Contributor

LGTM 👍 Merging as this is going into swarm branch for now.

Contributor

icecrime commented Jun 14, 2016

LGTM 👍 Merging as this is going into swarm branch for now.

@icecrime icecrime merged commit 8a378f2 into moby:swarm Jun 14, 2016

2 checks passed

docker/dco-signed All commits signed
Details
documentation success
Details

@sfsmithcha sfsmithcha deleted the sfsmithcha:swarm-docs branch Jul 12, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment