Merge pull request #6930 from JanMa/add-nspawn-driver

docs: add nspawn as external task driver plugin

website/data/docs-navigation.js

@@ -172,7 +172,8 @@ export default [
           'singularity',
           'jail-task-driver',
           'pot',
-          'firecracker-task-driver'
+          'firecracker-task-driver',
+          'nspawn'
         ]
       }
     ]

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

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