github.com/dkerwin/nomad@v0.3.3-0.20160525181927-74554135514b/website/source/docs/drivers/docker.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Drivers: Docker" 4 sidebar_current: "docs-drivers-docker" 5 description: |- 6 The Docker task driver is used to run Docker based tasks. 7 --- 8 9 # Docker Driver 10 11 Name: `docker` 12 13 The `docker` driver provides a first-class Docker workflow on Nomad. The Docker 14 driver handles downloading containers, mapping ports, and starting, watching, 15 and cleaning up after containers. 16 17 ## Task Configuration 18 19 The `docker` driver is configured via a `config` block: 20 21 ``` 22 task "webservice" { 23 driver = "docker" 24 config = { 25 image = "redis" 26 labels = { 27 group = "webservice-cache" 28 } 29 } 30 } 31 ``` 32 33 The following options are available for use in the job specification. 34 35 * `image` - The Docker image to run. The image may include a tag or custom URL and should include `https://` if required. 36 By default it will be fetched from Docker Hub. 37 38 * `load` - (Optional) A list of paths to image archive files. If 39 this key is not specified, Nomad assumes the `image` is hosted on a repository 40 and attempts to pull the image. The `artifact` blocks can be specified to 41 download each of the archive files. The equivalent of `docker load -i path` 42 would be run on each of the archive files. 43 44 * `command` - (Optional) The command to run when starting the container. 45 46 * `args` - (Optional) A list of arguments to the optional `command`. If no 47 `command` is present, `args` are ignored. References to environment variables 48 or any [interpretable Nomad 49 variables](/docs/jobspec/interpreted.html) will be interpreted 50 before launching the task. For example: 51 52 ``` 53 args = ["${nomad.datacenter}", "${MY_ENV}", "${meta.foo}"] 54 ``` 55 56 * `labels` - (Optional) A key/value map of labels to set to the containers on 57 start. 58 59 * `privileged` - (Optional) `true` or `false` (default). Privileged mode gives 60 the container access to devices on the host. Note that this also requires the 61 nomad agent and docker daemon to be configured to allow privileged 62 containers. 63 64 * `ipc_mode` - (Optional) The IPC mode to be used for the container. The default 65 is `none` for a private IPC namespace. Other values are `host` for sharing 66 the host IPC namespace or the name or id of an existing container. Note that 67 it is not possible to refer to Nomad started Docker containers since their 68 names are not known in advance. Note that setting this option also requires the 69 Nomad agent to be configured to allow privileged containers. 70 71 * `pid_mode` - (Optional) `host` or not set (default). Set to `host` to share 72 the PID namespace with the host. Note that this also requires the Nomad agent 73 to be configured to allow privileged containers. 74 75 * `uts_mode` - (Optional) `host` or not set (default). Set to `host` to share 76 the UTS namespace with the host. Note that this also requires the Nomad agent 77 to be configured to allow privileged containers. 78 79 * `network_mode` - (Optional) The network mode to be used for the container. In 80 order to support userspace networking plugins in Docker 1.9 this accepts any 81 value. The default is `bridge`. Other networking modes may not work without 82 additional configuration on the host (which is outside the scope of Nomad). 83 Valid values pre-docker 1.9 are `default`, `bridge`, `host`, `none`, or 84 `container:name`. See below for more details. 85 86 * `hostname` - (Optional) The hostname to assign to the container. When 87 launching more than one of a task (using `count`) with this option set, every 88 container the task starts will have the same hostname. 89 90 * `dns_servers` - (Optional) A list of DNS servers for the container to use 91 (e.g. ["8.8.8.8", "8.8.4.4"]). *Docker API v1.10 and above only* 92 93 * `dns_search_domains` - (Optional) A list of DNS search domains for the container 94 to use. 95 96 * `SSL` - (Optional) If this is set to true, Nomad uses SSL to talk to the 97 repository. The default value is `false`. 98 99 * `port_map` - (Optional) A key/value map of port labels (see below). 100 101 * `auth` - (Optional) Provide authentication for a private registry (see below). 102 103 * `tty` - (Optional) `true` or `false` (default). Allocate a pseudo-TTY for the 104 container. 105 106 * `interactive` - (Optional) `true` or `false` (default). Keep STDIN open on 107 the container. 108 109 ### Container Name 110 111 Nomad creates a container after pulling an image. Containers are named 112 `{taskName}-{allocId}`. This is necessary in order to place more than one 113 container from the same task on a host (e.g. with count > 1). This also means 114 that each container's name is unique across the cluster. 115 116 This is not configurable. 117 118 ### Authentication 119 120 If you want to pull from a private repo (for example on dockerhub or quay.io), 121 you will need to specify credentials in your job via the `auth` option. 122 123 The `auth` object supports the following keys: 124 125 * `username` - (Optional) The account username. 126 127 * `password` - (Optional) The account password. 128 129 * `email` - (Optional) The account email. 130 131 * `server_address` - (Optional) The server domain/ip without the protocol. 132 Docker Hub is used by default. 133 134 Example: 135 136 ``` 137 task "secretservice" { 138 driver = "docker" 139 140 config { 141 image = "secret/service" 142 143 auth { 144 username = "dockerhub_user" 145 password = "dockerhub_password" 146 } 147 } 148 } 149 ``` 150 151 **Please note that these credentials are stored in Nomad in plain text.** 152 Secrets management will be added in a later release. 153 154 ## Networking 155 156 Docker supports a variety of networking configurations, including using host 157 interfaces, SDNs, etc. Nomad uses `bridged` networking by default, like Docker. 158 159 You can specify other networking options, including custom networking plugins 160 in Docker 1.9. **You may need to perform additional configuration on the host 161 in order to make these work.** This additional configuration is outside the 162 scope of Nomad. 163 164 ### Allocating Ports 165 166 You can allocate ports to your task using the port syntax described on the 167 [networking page](/docs/jobspec/networking.html). Here is a recap: 168 169 ``` 170 task "webservice" { 171 driver = "docker" 172 173 port "http" {} 174 port "https" {} 175 } 176 ``` 177 178 ### Forwarding and Exposing Ports 179 180 A Docker container typically specifies which port a service will listen on by 181 specifying the `EXPOSE` directive in the `Dockerfile`. 182 183 Because dynamic ports will not match the ports exposed in your Dockerfile, 184 Nomad will automatically expose all of the ports it allocates to your 185 container. 186 187 These ports will be identified via environment variables. For example: 188 189 ``` 190 port "http" {} 191 ``` 192 193 If Nomad allocates port `23332` to your task for `http`, `23332` will be 194 automatically exposed and forwarded to your container, and the driver will set 195 an environment variable `NOMAD_PORT_http` with the value `23332` that you can 196 read inside your container. 197 198 This provides an easy way to use the `host` networking option for better 199 performance. 200 201 ### Using the Port Map 202 203 If you prefer to use the traditional port-mapping method, you can specify the 204 `port_map` option in your job specification. It looks like this: 205 206 ``` 207 task "redis" { 208 driver = "docker" 209 210 port "redis" {} 211 212 config { 213 image = "redis" 214 215 port_map { 216 redis = 6379 217 } 218 } 219 } 220 ``` 221 222 If Nomad allocates port `23332` to your task, the Docker driver will 223 automatically setup the port mapping from `23332` on the host to `6379` in your 224 container, so it will just work! 225 226 Note that by default this only works with `bridged` networking mode. It may 227 also work with custom networking plugins which implement the same API for 228 expose and port forwarding. 229 230 ### Networking Protocols 231 232 The Docker driver configures ports on both the `tcp` and `udp` protocols. 233 234 This is not configurable. 235 236 ### Other Networking Modes 237 238 Some networking modes like `container` or `none` will require coordination 239 outside of Nomad. First-class support for these options may be improved later 240 through Nomad plugins or dynamic job configuration. 241 242 ## Host Requirements 243 244 Nomad requires Docker to be installed and running on the host alongside the 245 Nomad agent. Nomad was developed against Docker `1.8.2` and `1.9`. 246 247 By default Nomad communicates with the Docker daemon using the daemon's unix 248 socket. Nomad will need to be able to read/write to this socket. If you do not 249 run Nomad as root, make sure you add the Nomad user to the Docker group so 250 Nomad can communicate with the Docker daemon. 251 252 For example, on ubuntu you can use the `usermod` command to add the `vagrant` 253 user to the `docker` group so you can run Nomad without root: 254 255 sudo usermod -G docker -a vagrant 256 257 For the best performance and security features you should use recent versions 258 of the Linux Kernel and Docker daemon. 259 260 ## Agent Configuration 261 262 The `docker` driver has the following [client configuration 263 options](/docs/agent/config.html#options): 264 265 * `docker.endpoint` - Defaults to `unix:///var/run/docker.sock`. You will need 266 to customize this if you use a non-standard socket (http or another 267 location). 268 269 * `docker.auth.config` - Allows an operator to specify a json file which is in 270 the dockercfg format containing authentication information for private registry. 271 272 * `docker.tls.cert` - Path to the server's certificate file (`.pem`). Specify 273 this along with `docker.tls.key` and `docker.tls.ca` to use a TLS client to 274 connect to the docker daemon. `docker.endpoint` must also be specified or 275 this setting will be ignored. 276 277 * `docker.tls.key` - Path to the client's private key (`.pem`). Specify this 278 along with `docker.tls.cert` and `docker.tls.ca` to use a TLS client to 279 connect to the docker daemon. `docker.endpoint` must also be specified or 280 this setting will be ignored. 281 282 * `docker.tls.ca` - Path to the server's CA file (`.pem`). Specify this along 283 with `docker.tls.cert` and `docker.tls.key` to use a TLS client to connect to 284 the docker daemon. `docker.endpoint` must also be specified or this setting 285 will be ignored. 286 287 * `docker.cleanup.image` Defaults to `true`. Changing this to `false` will 288 prevent Nomad from removing images from stopped tasks. 289 290 * `docker.privileged.enabled` Defaults to `false`. Changing this to `true` will 291 allow containers to use `privileged` mode, which gives the containers full 292 access to the host's devices. Note that you must set a similar setting on the 293 Docker daemon for this to work. 294 `true` will also allow containers to run with ipc_mode, pid_mode and uts_mode 295 set to `host`, which gives access to the hosts ipc, pid and UTS namespaces 296 respectively. 297 298 cert := d.config.Read("docker.tls.cert") 299 key := d.config.Read("docker.tls.key") 300 ca := d.config.Read("docker.tls.ca") 301 302 Note: When testing or using the `-dev` flag you can use `DOCKER_HOST`, 303 `DOCKER_TLS_VERIFY`, and `DOCKER_CERT_PATH` to customize Nomad's behavior. If 304 `docker.endpoint` is set Nomad will **only** read client configuration from the 305 config filie. 306 307 An example is given below: 308 309 ``` 310 client { 311 options = { 312 "docker.cleanup.image" = "false" 313 } 314 } 315 ``` 316 317 ## Agent Attributes 318 319 The `docker` driver will set the following client attributes: 320 321 * `driver.docker` - This will be set to "1", indicating the driver is 322 available. 323 * `driver.docker.version` - This will be set to version of the docker server 324 325 ## Resource Isolation 326 327 ### CPU 328 329 Nomad limits containers' CPU based on CPU shares. CPU shares allow containers 330 to burst past their CPU limits. CPU limits will only be imposed when there is 331 contention for resources. When the host is under load your process may be 332 throttled to stabilize QOS depending on how many shares it has. You can see how 333 many CPU shares are available to your process by reading `NOMAD_CPU_LIMIT`. 334 1000 shares are approximately equal to 1Ghz. 335 336 Please keep the implications of CPU shares in mind when you load test workloads 337 on Nomad. 338 339 ### Memory 340 341 Nomad limits containers' memory usage based on total virtual memory. This means 342 that containers scheduled by Nomad cannot use swap. This is to ensure that a 343 swappy process does not degrade performance for other workloads on the same 344 host. 345 346 Since memory is not an elastic resource, you will need to make sure your 347 container does not exceed the amount of memory allocated to it, or it will be 348 terminated or crash when it tries to malloc. A process can inspect its memory 349 limit by reading `NOMAD_MEMORY_LIMIT`, but will need to track its own memory 350 usage. Memory limit is expressed in megabytes so 1024 = 1Gb. 351 352 ### IO 353 354 Nomad's Docker integration does not currently provide QOS around network or 355 filesystem IO. These will be added in a later release. 356 357 ### Security 358 359 Docker provides resource isolation by way of 360 [cgroups and namespaces](https://docs.docker.com/introduction/understanding-docker/#the-underlying-technology). 361 Containers essentially have a virtual file system all to themselves. If you 362 need a higher degree of isolation between processes for security or other 363 reasons, it is recommended to use full virtualization like 364 [QEMU](/docs/drivers/qemu.html).