Nomad Systemd-Nspawn driver

This is a task driver for Hashicorp Nomad to run containers with systemd-nspawn.

Containers started via this driver will have private networking enabled by default and their machine ID will be set to the allocation ID of the started Nomad task.

Client requirements

• Nomad 1.4.0+ running as root
• Go 1.20
• Linux
• systemd-nspawn installed

Building the driver from source

Checkout this repository and simply run make.

$ git clone https://github.com/JanMa/nomad-driver-nspawn.git
$ cd nomad-driver-nspawn
$ make

Testing the driver

To execute the built-in test suite run

$ make test

Using the driver

To test the driver, run the Nomad agent in development mode with the following command

$ sudo nomad agent -dev -plugin-dir=$(pwd) -config=example/config.hcl

Minimal job example

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

Argument reference

The driver supports the following subset of possible arguments from systemd-nspawn, which should cover a broad range of use cases:

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

• private_users - (Optional). Controls how user namespacing is enabled. For this option to take effect, user_namespacing needs to be set to true.

• private_users_ownership - (Optional). Controls how to adjust the container image's UIDs and GIDs to match the UID/GID range chosen with private_users. For this option to take effect, user_namespacing needs to be set to true.

• 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 be the 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 container's 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) DEPRECATED 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
    }
  }

• ports - (Optional) A list 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 {
    ports = ["http"]
  }

• capability - (Optional) List of additional capabilities to grant the container.

  config {
    capability = ["CAP_NET_ADMIN"]
  }

• network_veth - (Optional) true (default) or false. Create a virtual ethernet link between the host and the container.

• network_bridge - (Optional) Attach the virtual container interface to a host side bridge that must already exist.

• network_zone - (Optional) Start the container in the given network zone. Each container may only be part of one zone, but each zone may contain any number of containers.

The image_download block supports the following arguments:

• url - The URL of the image to download. The URL must be of type http://, https:// or a valid docker image reference. This option is mandatory.
• verify - (Optional) no (default), signature or checksum. Whether to verify the image before making it available. This option has no effect when downloading docker images.
• 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), raw or docker. The type of image to download.