Nomad Docker Wrapper

Description

Small wrapper to enable running arbitrary docker run commands in Nomad. This is useful when you require features that are not supported by the Nomad docker task driver.

Usage

You can use the wrapper script as a job artifact to run your docker container with the specified arguments.

Docker Container Name

Using a named container will ensure that it gets removed properly the next time you start it again. You have to provide NOMAD_DOCKER_CONTAINER_NAME as an environment variable.

Docker Pull Before Run

If you are using the "latest" tag of an image and want to pull it before running, you can specify the image to pull by setting NOMAD_DOCKER_PULL_COMMAND.

Environment Variable Replacement

If you want to use environment variables inside your docker command that are passed by Nomad (e.g. dynamic ports), you can include them as a String and rely on the wrapper to replace them. To accomplish this, just set NOMAD_DOCKER_ENVSUBST to any value.

Please make sure that envsubst is installed on your system when using this option. It is part of the gettext package: apt-get install gettext.

Private Docker Registry

If you want to use a custom docker registry, please provide the NOMAD_DOCKER_REGISTRY_URL alongside with the credentials. For details, see the configuration section.

CAUTION: The credentials will be passed as environment variables to the Nomad job. Everyone who can query for these environment variables through the Nomad API is able to see your registry credentials. Better practice is to make sure all Nomad nodes are logged into the docker registry already.

Examples

Below are examples that start a simple python web server inside a container and expose the respective port. While it is technically possible to use the wrapper from the shell, it is not very useful. The intended use case is within Nomad.

Shell

NOMAD_DOCKER_CONTAINER_NAME=http-server \
bash <(curl -s https://raw.githubusercontent.com/FRosner/nomad-docker-wrapper/master/nomad-docker-wrapper) \
-p 8000:8000 python:alpine python -m http.server

Nomad

job "http-job" {
  datacenters = ["dc1"]
  group "http-group" {
    task "http-task" {
      driver = "raw_exec"

      artifact {
        source = "https://raw.githubusercontent.com/FRosner/nomad-docker-wrapper/master/nomad-docker-wrapper"
      }

      env {
        NOMAD_DOCKER_CONTAINER_NAME = "${NOMAD_TASK_NAME}"
        NOMAD_DOCKER_ENVSUBST = 1
      }

      config {
        command = "nomad-docker-wrapper"
        args = ["-p", "$NOMAD_PORT_http:8000", "python:alpine", "python", "-m", "http.server"]
      }

      resources {
        cpu = 500
        memory = 128
        network {
          mbits = 10
          port "http" {}
        }
      }
    }
  }
}

Configuration

You can use environment variables to configure the wrapper. Below is a list of supported variables. The ones marked with * are mandatory.

Variable	Description
`NOMAD_DOCKER_CONTAINER_NAME`*	Container name to be used on the docker host.
`NOMAD_DOCKER_ENVSUBST`	Set this to apply `envsubst` to your docker command before running it.
`NOMAD_DOCKER_REGISTRY_URL`	URL of your private docker registry. If this is set, the wrapper will attempt to login.
`NOMAD_DOCKER_REGISTRY_USER`	User to use for logging into your private docker registry.
`NOMAD_DOCKER_REGISTRY_PASSWORD`	Password to use for logging into your private docker registry.
`NOMAD_DOCKER_REGISTRY_EMAIL`	Email address to use for logging into your private docker registry.
`NOMAD_DOCKER_PULL_COMMAND`	Arguments to pass to `docker pull` which will get execute before `docker run`.

Gerrrr / nomad-docker-wrapper