nspawn Driver

Name: nspawn

The nspawn driver provides an interface for using systemd-nspawn for running application containers. You can download the external systemd-nspawn driver here. For more detailed instructions on how to set up and use this driver, please refer to the guide.

Task Configuration

task "debian" {
  driver = "nspawn"
  config {
    image = "/var/lib/machines/Debian"
    resolv_conf = "copy-host"
  }
}

The nspawn driver supports the following configuration in the job spec:

boot - (Optional) true (default) or false. Search for an init program and invoke it as PID 1. Arguments specified in command will be used as arguments for the init program.
ephemeral - (Optional) true or false (default). Make an ephemeral copy of the image before staring the container.
process_two - (Optional) true or false (default). Start the command specified with command as PID 2, using a minimal stub init as PID 1.
read_only - (Optional) true or false (default). Mount the used image as read only.
user_namespacing - (Optional) true (default) or false. Enable user namespacing features inside the container.

command - (Optional) A list of strings to pass as the used command to the container.

config {
  command = [ "/bin/bash", "-c", "dhclient && nginx && tail -f /var/log/nginx/access.log" ]
}

console - (Optional) Configures how to set up standard input, output and error output for the container.
image - The image to be used in the container. This can either be the path to a directory, the path to a file system image or block device or the name of an image registered with systemd-machined. A path can be specified as a relative path from the configured Nomad plugin directory. This option is mandatory.
image_download - (Optional) Download the used image according to the settings defined in this block. Structure is documented below.
pivot_root - (Optional) Pivot the specified directory to the be containers root directory.
resolv_conf - (Optional) Configure how /etc/resolv.conf is handled inside the container.
user - (Optional) Change to the specified user in the containers user database.
volatile - (Optional) Boot the container in volatile mode.
working_directory - (Optional) Set the working directory inside the container.

bind - (Optional) Files or directories to bind mount inside the container.

config {
  bind {
    "/var/lib/postgresql" = "/postgres"
  }
}

bind_read_only - (Optional) Files or directories to bind mount read only inside the container.
```
config {
  bind_read_only {
    "/etc/passwd" = "/etc/passwd"
  }
}
```
environment - (Optional) Environment variables to pass to the init process in the container.
```
config {
  environment = {
    FOO = "bar"
  }
}
```
port_map - (Optional) A key-value map of port labels. Works the same way as in the docker driver.
Note: systemd-nspawn will not expose ports to the loopback interface of your host.
```
config {
  port_map {
    http = 80
  }
}
```

The image_download block supports the following arguments:

url - The URL of the image to download. The URL must be of type http:// or https://. This option is mandatory.
verify - (Optional) no (default), signature or checksum. Whether to verify the image before making it available.
force - (Optional) true or false (default) If a local copy already exists, delete it first and replace it by the newly downloaded image.
type - (Optional) tar (default) or raw. The type of image to download.

Networking

The nspawn driver has support for host networking and also bridge mode networking. It can therefore be used with Nomad's Consul Connect integration.

Client Requirements

The nspawn driver requires the following:

64-bit Linux host
The linux_amd64 Nomad binary
The nspawn driver binary placed in the plugin_dir directory.
systemd-nspawn to be installed
Nomad running with root privileges

Plugin Options

enabled - The nspawn driver may be disabled on hosts by setting this option to false (defaults to true).
volumes - Enable support for Volumes in the driver (defaults to true).

An example of using these plugin options with the new plugin syntax is shown below:

plugin "nspawn" {
  config {
    enabled = true
    volumes = true
  }
}

Client Attributes

The nspawn driver will set the following client attributes:

driver.nspawn - Set to true if systemd-nspawn is found and enabled on the host node and Nomad is running with root privileges.
driver.nspawn.version - Version of systemd-nspawn e.g.: 244.