diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 441b5092f..2e72c5c0e 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -172,7 +172,8 @@ export default [ 'singularity', 'jail-task-driver', 'pot', - 'firecracker-task-driver' + 'firecracker-task-driver', + 'nspawn' ] } ] diff --git a/website/pages/docs/drivers/external/index.mdx b/website/pages/docs/drivers/external/index.mdx index ffbb0abd7..158dad360 100644 --- a/website/pages/docs/drivers/external/index.mdx +++ b/website/pages/docs/drivers/external/index.mdx @@ -27,6 +27,7 @@ Below is a list of community-supported task drivers you can use with Nomad: - [Jail task driver][jail-task-driver] - [Pot][pot] - [Firecracker][firecracker-task-driver] +- [Systemd-Nspawn][nspawn-driver] [lxc]: /docs/drivers/external/lxc [plugin_guide]: /docs/internals/plugins @@ -35,3 +36,4 @@ Below is a list of community-supported task drivers you can use with Nomad: [podman]: /docs/drivers/external/podman [pot]: /docs/drivers/external/pot [firecracker-task-driver]: /docs/drivers/external/firecracker-task-driver +[nspawn-driver]: /docs/drivers/external/nspawn diff --git a/website/pages/docs/drivers/external/nspawn.mdx b/website/pages/docs/drivers/external/nspawn.mdx new file mode 100644 index 000000000..78eb7458c --- /dev/null +++ b/website/pages/docs/drivers/external/nspawn.mdx @@ -0,0 +1,162 @@ +--- +layout: docs +page_title: 'Drivers: Systemd-Nspawn' +sidebar_title: Systemd-Nspawn +description: The Nspawn task driver is used to run application containers using Systemd-Nspawn. +--- + +# 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][nspawn-driver]. For more detailed instructions on how to set up and use this driver, please refer to the [guide][nspawn-guide]. + +## Task Configuration + +```hcl +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`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-b) - + (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`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-x) - + (Optional) `true` or `false` (default). Make an ephemeral copy of the image + before staring the container. +* [`process_two`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-a) - + (Optional) `true` or `false` (default). Start the command specified with + `command` as PID 2, using a minimal stub init as PID 1. +* [`read_only`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--read-only) - + (Optional) `true` or `false` (default). Mount the used image as read only. +* [`user_namespacing`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-U) - + (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. + + ```hcl + config { + command = [ "/bin/bash", "-c", "dhclient && nginx && tail -f /var/log/nginx/access.log" ] + } + ``` +* [`console`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--console=MODE) - + (Optional) Configures how to set up standard input, output and error output + for the container. +* `image` - Path to the image to be used in the container. This can either be a + [directory](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-D) + or the path to a file system + [image](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-i) + or block device. Can be specified as a relative path from the configured Nomad + plugin directory. **This option is mandatory**. +* [`pivot_root`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--pivot-root=) - + (Optional) Pivot the specified directory to the be containers root directory. +* [`resolv_conf`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--resolv-conf=) - + (Optional) Configure how `/etc/resolv.conf` is handled inside the container. +* [`user`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-u) - + (Optional) Change to the specified user in the containers user database. +* [`volatile`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--volatile) - + (Optional) Boot the container in volatile mode. +* [`working_directory`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--chdir=) - + (Optional) Set the working directory inside the container. +* [`bind`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--bind=) - + (Optional) Files or directories to bind mount inside the container. + + ```hcl + config { + bind { + "/var/lib/postgresql" = "/postgres" + } + } + ``` +* [`bind_read_only`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--bind=) - + (Optional) Files or directories to bind mount read only inside the container. + + ```hcl + config { + bind_read_only { + "/etc/passwd" = "/etc/passwd" + } + } + + ``` +* `environment` - (Optional) Environment variables to pass to the init process + in the container. + + ```hcl + config { + environment = { + FOO = "bar" + } + } + ``` +* `port_map` - (Optional) A key-value map of port labels. Works the same way as + in the [docker + driver][docker_driver]. + **Note:** `systemd-nspawn` will not expose ports to the loopback interface of + your host. + + ```hcl + config { + port_map { + http = 80 + } + } + ``` + + +## Networking + +Currently the `nspawn` driver only supports host networking. + +## 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][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`). + +An example of using these plugin options with the new [plugin +syntax][plugin] is shown below: + +```hcl +plugin "nspawn" { + config { + enabled = 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`. + + +[nspawn-driver]: https://github.com/JanMa/nomad-driver-nspawn/releases +[nspawn-guide]: https://github.com/JanMa/nomad-driver-nspawn +[plugin]: /docs/configuration/plugin +[plugin_dir]: /docs/configuration#plugin_dir +[plugin-options]: #plugin-options +[client_options]: /docs/configuration/client#options +[docker_driver]: /docs/drivers/docker#using-the-port-map