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).