1. docker
  2. Commit c79ef9842abb826037bc22bda563df53d76e99c6
Browse code

Merge pull request #25197 from sfsmithcha/add_services_guide

author merge: add services guide to manage a swarm
(cherry picked from commit 8b69d50c79f75f670fdc87e3e19c651551726605)

Charles Smith authored on 2016/07/30 07:33:34
Showing 1 changed files
docs/swarm/services.md
History View file @ c79ef98
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,328 @@
0 
+<!--[metadata]>
1 
+title = "Deploy services to a swarm"
2 
+description = "Deploy services to a swarm"
3 
+keywords = ["guide", "swarm mode", "swarm", "service"]
4 
+[menu.main]
5 
+identifier="services-guide"
6 
+parent="engine_swarm"
7 
+weight=15
8 
+<![end-metadata]-->
9 
+
10 
+# Deploy services to a swarm
11 
+
12 
+When you are running Docker Engine in swarm mode, you run
13 
+`docker service create` to deploy your application in the swarm. The swarm
14 
+manager accepts the service description as the desired state for your
15 
+application. The built-in swarm orchestrator and scheduler deploy your
16 
+application to nodes in your swarm to achieve and maintain the desired state.
17 
+
18 
+For an overview of how services work, refer to [How services work](how-swarm-mode-works/services.md).
19 
+
20 
+This guide assumes you are working with the Docker Engine running in swarm
21 
+mode. You must run all `docker service` commands from a manager node.
22 
+
23 
+If you haven't already, read through [Swarm mode key concepts](key-concepts.md)
24 
+and [How services work](how-swarm-mode-works/services.md).
25 
+
26 
+## Create a service
27 
+
28 
+To create the simplest type of service in a swarm, you only need to supply
29 
+a container image:
30 
+
31 
+```bash
32 
+$ docker service create <IMAGE>
33 
+```
34 
+
35 
+The swarm orchestrator schedules one task on an available node. The task invokes
36 
+a container based upon the image. For example, you could run the following
37 
+command to create a service of one instance of an nginx web server:
38 
+
39 
+```bash
40 
+$ docker service create --name my_web nginx
41 
+
42 
+anixjtol6wdfn6yylbkrbj2nx
43 
+```
44 
+
45 
+In this example the `--name` flag names the service `my_web`.
46 
+
47 
+To list the service, run `docker service ls` from a manager node:
48 
+
49 
+```bash
50 
+$ docker service ls
51 
+
52 
+ID            NAME    REPLICAS  IMAGE  COMMAND
53 
+anixjtol6wdf  my_web  1/1       nginx
54 
+```
55 
+
56 
+To make the web server accessible from outside the swarm, you need to
57 
+[publish the port](#publish-ports-externally-to-the-swarm) where the swarm
58 
+listens for web requests.
59 
+
60 
+You can include a command to run inside containers after the image:
61 
+
62 
+```bash
63 
+$ docker service create <IMAGE> <COMMAND>
64 
+```
65 
+
66 
+For example to start an `alpine` image that runs `ping docker.com`:
67 
+
68 
+```bash
69 
+$ docker service create --name helloworld alpine ping docker.com
70 
+
71 
+9uk4639qpg7npwf3fn2aasksr
72 
+```
73 
+
74 
+## Configure the runtime environment
75 
+
76 
+You can configure the following options for the runtime environment in the
77 
+container:
78 
+
79 
+* environment variables using the `--env` flag
80 
+* the working directory inside the container using the `--workdir` flag
81 
+* the username or UID using the `--user` flag
82 
+
83 
+For example:
84 
+
85 
+```bash
86 
+$ docker service create --name helloworld \
87 
+  --env MYVAR=myvalue \
88 
+  --workdir /tmp \
89 
+  --user my_user \
90 
+  alpine ping docker.com
91 
+
92 
+9uk4639qpg7npwf3fn2aasksr
93 
+```
94 
+
95 
+## Control service scale and placement
96 
+
97 
+Swarm mode has two types of services, replicated and global. For replicated
98 
+services, you specify the number of replica tasks for the swarm manager to
99 
+schedule onto available nodes. For global services, the scheduler places one
100 
+task on each available node.
101 
+
102 
+You control the type of service using the `--mode` flag. If you don't specify a
103 
+mode, the service defaults to `replicated`. For replicated services, you specify
104 
+the number of replica tasks you want to start using the `--replicas` flag. For
105 
+example, to start a replicated nginx service with 3 replica tasks:
106 
+
107 
+```bash
108 
+$ docker service create --name my_web --replicas 3 nginx
109 
+```
110 
+
111 
+To start a global service on each available node, pass `--mode global` to
112 
+`docker service create`. Every time a new node becomes available, the scheduler
113 
+places a task for the global service on the new node. For example to start a
114 
+service that runs alpine on every node in the swarm:
115 
+
116 
+```bash
117 
+$ docker service create --name myservice --mode global alpine top
118 
+```
119 
+
120 
+Service constraints let you set criteria for a node to meet before the scheduler
121 
+deploys a service to the node. You can apply constraints to the
122 
+service based upon node attributes and metadata or engine metadata. For more
123 
+information on constraints, refer to the `docker service create` [CLI  reference](../reference/commandline/service_create.md).
124 
+
125 
+
126 
+## Configure service networking options
127 
+
128 
+Swarm mode lets you network services in a couple of ways:
129 
+
130 
+* publish ports externally to the swarm using ingress networking
131 
+* connect services and tasks within the swarm using overlay networks
132 
+
133 
+### Publish ports externally to the swarm
134 
+
135 
+You publish service ports externally to the swarm using the `--publish
136 
+<TARGET-PORT>:<SERVICE-PORT>` flag. When you publish a service port, the swarm
137 
+makes the service accessible at the target port on every node regardless if
138 
+there is a task for the service running on the node.
139 
+
140 
+For example, imagine you want to deploy a 3-replica nginx service to a 10-node
141 
+swarm as follows:
142 
+
143 
+```bash
144 
+docker service create --name my_web --replicas 3 --publish 8080:80 nginx
145 
+```
146 
+
147 
+The scheduler will deploy nginx tasks to a maximum of 3 nodes. However, the
148 
+swarm makes nginx port 80 from the task container accessible at port 8080 on any
149 
+node in the swarm. You can direct `curl` at port 8080 of any node in the swarm
150 
+to access the web server:
151 
+
152 
+```bash
153 
+$ curl localhost:8080
154 
+
155 
+<!DOCTYPE html>
156 
+<html>
157 
+<head>
158 
+<title>Welcome to nginx!</title>
159 
+<style>
160 
+    body {
161 
+        width: 35em;
162 
+        margin: 0 auto;
163 
+        font-family: Tahoma, Verdana, Arial, sans-serif;
164 
+    }
165 
+</style>
166 
+</head>
167 
+<body>
168 
+<h1>Welcome to nginx!</h1>
169 
+<p>If you see this page, the nginx web server is successfully installed and
170 
+working. Further configuration is required.</p>
171 
+
172 
+<p>For online documentation and support please refer to
173 
+<a href="http://nginx.org/">nginx.org</a>.<br/>
174 
+Commercial support is available at
175 
+<a href="http://nginx.com/">nginx.com</a>.</p>
176 
+
177 
+<p><em>Thank you for using nginx.</em></p>
178 
+</body>
179 
+</html>
180 
+```
181 
+
182 
+### Add an overlay network
183 
+
184 
+Use overlay networks to connect one or more services within the swarm.
185 
+
186 
+First, create an overlay network on a manager node the `docker network create`
187 
+command:
188 
+
189 
+```bash
190 
+$ docker network create --driver overlay my-network
191 
+
192 
+etjpu59cykrptrgw0z0hk5snf
193 
+```
194 
+
195 
+After you create an overlay network in swarm mode, all manager nodes have access
196 
+to the network.
197 
+
198 
+When you create a service and pass the `--network` flag to attach the service to
199 
+the overlay network:
200 
+
201 
+```bash
202 
+$ docker service create \
203 
+  --replicas 3 \
204 
+  --network my-multi-host-network \
205 
+  --name my-web \
206 
+  nginx
207 
+
208 
+716thylsndqma81j6kkkb5aus
209 
+```
210 
+
211 
+The swarm extends `my-network` to each node running the service.
212 
+
213 
+<!-- TODO when overlay-security-model is published
214 
+For more information, refer to [Note on Docker 1.12 Overlay Network Security Model](../userguide/networking/overlay-security-model.md).-->
215 
+
216 
+## Configure update behavior
217 
+
218 
+When you create a service, you can specify a rolling update behavior for how the
219 
+swarm should apply changes to the service when you run `docker service update`.
220 
+You can also specify these flags as part of the update, as arguments to
221 
+`docker service update`.
222 
+
223 
+The `--update-delay` flag configures the time delay between updates to a service
224 
+task or sets of tasks. You can describe the time `T` as a combination of the
225 
+number of seconds `Ts`, minutes `Tm`, or hours `Th`. So `10m30s` indicates a 10
226 
+minute 30 second delay.
227 
+
228 
+By default the scheduler updates 1 task at a time. You can pass the
229 
+`--update-parallelism` flag to configure the maximum number of service tasks
230 
+that the scheduler updates simultaneously.
231 
+
232 
+When an update to an individual task returns a state of `RUNNING`, the scheduler
233 
+continues the update by continuing to another task until all tasks are updated.
234 
+If, at any time during an update a task returns `FAILED`, the scheduler pauses
235 
+the update. You can control the behavior using the `--update-failure-action`
236 
+flag for `docker service create` or `docker service update`.
237 
+
238 
+In the example service below, the scheduler applies updates to a maximum of 2
239 
+replicas at a time. When an updated task returns either `RUNNING` or `FAILED`,
240 
+the scheduler waits 10 seconds before stopping the next task to update:
241 
+
242 
+```bash
243 
+$ docker service create \
244 
+  --replicas 10 \
245 
+  --name my_web \
246 
+  --update-delay 10s \
247 
+  --update-parallelism 2 \
248 
+  --update-failure-action continue \
249 
+  alpine
250 
+
251 
+0u6a4s31ybk7yw2wyvtikmu50
252 
+```
253 
+
254 
+## Configure mounts
255 
+
256 
+You can create two types of mounts for services in a swarm, `volume` mounts or
257 
+`bind` mounts. You pass the `--mount` flag when you create a service. The
258 
+default is a volume mount if you don't specify a type.
259 
+
260 
+* Volumes are storage that remain alive after a container for a task has
261 
+been removed. The preferred method to mount volumes is to leverage an existing
262 
+volume:
263 
+
264 
+```bash
265 
+$ docker service create \
266 
+  --mount src=<VOLUME-NAME>,dst=<CONTAINER-PATH> \
267 
+  --name myservice \
268 
+  <IMAGE>
269 
+```
270 
+
271 
+For more information on how to create a volume, see the `volume create` [CLI reference](../reference/commandline/volume_create.md).
272 
+
273 
+The following method creates the volume at deployment time when the scheduler
274 
+dispatches a task, just before the starting the container:
275 
+
276 
+```bash
277 
+$ docker service create \
278 
+  --mount type=volume,src=<VOLUME-NAME>,dst=<CONTAINER-PATH>,volume-driver=<DRIVER>,volume-opt=<KEY0>=<VALUE0>,volume-opt=<KEY1>=<VALUE1>
279 
+  --name myservice \
280 
+  <IMAGE>
281 
+```
282 
+
283 
+* Bind mounts are file system paths from the host where the scheduler deploys
284 
+the container for the task. Docker mounts the path into the container. The
285 
+file system path must exist before the swarm initializes the container for the
286 
+task.
287 
+
288 
+The following examples show bind mount syntax:
289 
+
290 
+```bash
291 
+# Mount a read-write bind
292 
+$ docker service create \
293 
+  --mount type=bind,src=<HOST-PATH>,dst=<CONTAINER-PATH> \
294 
+  --name myservice \
295 
+  <IMAGE>
296 
+
297 
+# Mount a read-only bind
298 
+$ docker service create \
299 
+  --mount type=bind,src=<HOST-PATH>,dst=<CONTAINER-PATH>,readonly \
300 
+  --name myservice \
301 
+  <IMAGE>
302 
+```
303 
+
304 
+>**Important note:** Bind mounts can be useful but they are also dangerous.  In
305 
+most cases, we recommend that you architect your application such that mounting
306 
+paths from the host is unnecessary. The main risks include the following:<br />
307 
+> <br />
308 
+> If you bind mount a host path into your service’s containers, the path
309 
+> must exist on every machine. The Docker swarm mode scheduler can schedule
310 
+> containers on any machine that meets resource availability requirements
311 
+> and satisfies all `--constraint`s you specify.<br />
312 
+> <br />
313 
+> The Docker swarm mode scheduler may reschedule your running service
314 
+> containers at any time if they become unhealthy or unreachable.<br />
315 
+> <br />
316 
+> Host bind mounts are completely non-portable.  When you use  bind mounts,
317 
+> there is no guarantee that your application will run the same way in
318 
+> development as it does in production.
319 
+
320 
+
321 
+## Learn More
322 
+
323 
+* [Swarm administration guide](admin_guide.md)
324 
+* [Docker Engine command line reference](../reference/commandline/index.md)
325 
+* [Swarm mode tutorial](swarm-tutorial/index.md)