github.com/kardianos/nomad@v0.1.3-0.20151022182107-b13df73ee850/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 supports the following configuration in the job specification: 20 21 * `image` - (Required) The Docker image to run. The image may include a tag or 22 custom URL. By default it will be fetched from Docker Hub. 23 24 * `command` - (Optional) The command to run when starting the container. 25 26 * `args` - (Optional) Arguments to the optional `command`. If no `command` is 27 present, `args` are ignored. 28 29 * `network_mode` - (Optional) The network mode to be used for the container. 30 Valid options are `default`, `bridge`, `host` or `none`. If nothing is 31 specified, the container will start in `bridge` mode. The `container` 32 network mode is not supported right now and is reported as an invalid 33 option. 34 35 ### Port Mapping 36 37 Nomad uses port binding to expose services running in containers using the port 38 space on the host's interface. For example, Nomad host running on `1.2.3.4` may 39 allocate port `22333` to a task, so you would access that service via 40 `1.2.3.4:22333`. 41 42 Nomad provides automatic and manual mapping schemes for Docker. You can use 43 either or both schemes for a task. Nomad binds both tcp and udp protocols to 44 ports used for Docker containers. This is not configurable. 45 46 Note: You are not required to map any ports, for example if your task is running 47 a crawler or aggregator and does not provide a network service. Tasks without a 48 port mapping will still be able to make outbound network connections. 49 50 #### Automatic Port Mapping 51 52 Typically when you create a Docker container you configure the service to start 53 listening on a port (or ports) when you start the container. For example, redis 54 starts listening on `6379` when you `docker run redis`. Nomad can support this by 55 mapping a random port on the host machine to the port inside the container. 56 57 You need to tell Nomad which ports your container is using so Nomad can map 58 allocated ports for you. You do so by specifying a **numeric port value** for 59 the `dynamic_ports` option in your job specification. 60 61 ``` 62 dynamic_ports = ["6379"] 63 # or 64 dynamic_ports = [6379] 65 ``` 66 67 This instructs Nomad to create a port mapping from the random port on the host 68 to the port inside the container. So in our example above, when you contact the 69 host on `1.2.3.4:22333` you will actually hit the service running inside the 70 container on port `6379`. You can see which port was actually bound by reading the 71 `NOMAD_PORT_6379` [environment variable](/docs/jobspec/environment.html). 72 73 In most cases, the automatic port mapping will be the easiest to use, but you 74 can also use manual port mapping (described below). 75 76 #### Manual Port Mapping 77 78 The `dynamic_ports` option takes any alphanumeric string as a label, so you could 79 also specify a label for the port like `http` or `admin` to designate how the 80 port will be used. 81 82 In this case, Nomad doesn't know which container port to map to, so it maps 1:1 83 with the host port. For example, `1.2.3.4:22333` will map to `22333` inside the 84 container. 85 86 ``` 87 dynamic_ports = ["http"] 88 ``` 89 90 Your process will need to read the `NOMAD_PORT_HTTP` environment variable to 91 determine which port to bind to. 92 93 ## Client Requirements 94 95 Nomad requires Docker to be installed and running on the host alongside the Nomad 96 agent. Nomad was developed against Docker `1.8.2`. 97 98 By default Nomad communicates with the Docker daemon using the daemon's 99 unix socket. Nomad will need to be able to read/write to this socket. If you do 100 not run Nomad as root, make sure you add the Nomad user to the Docker group so 101 Nomad can communicate with the Docker daemon. 102 103 For example, on ubuntu you can use the `usermod` command to add the `vagrant` user to the 104 `docker` group so you can run Nomad without root: 105 106 sudo usermod -G docker -a vagrant 107 108 For the best performance and security features you should use recent versions of 109 the Linux Kernel and Docker daemon. 110 111 ## Client Configuration 112 113 The `docker` driver has the following configuration options: 114 115 * `docker.endpoint` - Defaults to `unix:///var/run/docker.sock`. You will need 116 to customize this if you use a non-standard socket (http or another location). 117 118 * `docker.cleanup.container` Defaults to `true`. Changing this to `false` will 119 prevent Nomad from removing containers from stopped tasks. 120 121 * `docker.cleanup.image` Defaults to `true`. Changing this to `false` will 122 prevent Nomad from removing images from stopped tasks. 123 124 Note: When testing or using the `-dev` flag you can use `DOCKER_HOST`, 125 `DOCKER_TLS_VERIFY`, and `DOCKER_CERT_PATH` to customize Nomad's behavior. In 126 production Nomad will always read `docker.endpoint`. 127 128 ## Client Attributes 129 130 The `docker` driver will set the following client attributes: 131 132 * `driver.docker` - This will be set to "1", indicating the 133 driver is available. 134 * `driver.docker.version` - This will be set to version of the 135 docker server 136 137 ## Resource Isolation 138 139 ### CPU 140 141 Nomad limits containers' CPU based on CPU shares. CPU shares allow containers to 142 burst past their CPU limits. CPU limits will only be imposed when there is 143 contention for resources. When the host is under load your process may be 144 throttled to stabilize QOS depending on how many shares it has. You can see how 145 many CPU shares are available to your process by reading `NOMAD_CPU_LIMIT`. 1000 146 shares are approximately equal to 1Ghz. 147 148 Please keep the implications of CPU shares in mind when you load test workloads 149 on Nomad. 150 151 ### Memory 152 153 Nomad limits containers' memory usage based on total virtual memory. This means 154 that containers scheduled by Nomad cannot use swap. This is to ensure that a 155 swappy process does not degrade performance for other workloads on the same host. 156 157 Since memory is not an elastic resource, you will need to make sure your 158 container does not exceed the amount of memory allocated to it, or it will be 159 terminated or crash when it tries to malloc. A process can inspect its memory 160 limit by reading `NOMAD_MEMORY_LIMIT`, but will need to track its own memory 161 usage. Memory limit is expressed in megabytes so 1024 = 1Gb. 162 163 ### IO 164 165 Nomad's Docker integration does not currently provide QOS around network or 166 filesystem IO. These will be added in a later release. 167 168 ### Security 169 170 Docker provides resource isolation by way of 171 [cgroups and namespaces](https://docs.docker.com/introduction/understanding-docker/#the-underlying-technology). 172 Containers essentially have a virtual file system all to themselves. If you need 173 a higher degree of isolation between processes for security or other reasons, it 174 is recommended to use full virtualization like [QEMU](/docs/drivers/qemu.html).