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