From 24312076e1ef13813caf71b0e82f50e3cee78816 Mon Sep 17 00:00:00 2001 From: Jan Martens Date: Sun, 12 Jan 2020 10:28:02 +0100 Subject: [PATCH 1/3] docs: add nspawn as external task driver plugin --- website/pages/docs/drivers/external/index.mdx | 2 + .../pages/docs/drivers/external/nspawn.mdx | 163 ++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 website/pages/docs/drivers/external/nspawn.mdx diff --git a/website/pages/docs/drivers/external/index.mdx b/website/pages/docs/drivers/external/index.mdx index ffbb0abd7c3..158dad36000 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 00000000000..01ff78664e6 --- /dev/null +++ b/website/pages/docs/drivers/external/nspawn.mdx @@ -0,0 +1,163 @@ +--- +layout: "docs" +page_title: "Drivers: Systemd-Nspawn" +sidebar_current: "docs-drivers-community-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 From ab017b8591de9667e14b3b0be457907aa2e0e5ee Mon Sep 17 00:00:00 2001 From: JanMa Date: Sat, 29 Feb 2020 18:07:15 +0100 Subject: [PATCH 2/3] fix page layout settings --- website/pages/docs/drivers/external/nspawn.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/website/pages/docs/drivers/external/nspawn.mdx b/website/pages/docs/drivers/external/nspawn.mdx index 01ff78664e6..78eb7458cff 100644 --- a/website/pages/docs/drivers/external/nspawn.mdx +++ b/website/pages/docs/drivers/external/nspawn.mdx @@ -1,9 +1,8 @@ --- -layout: "docs" -page_title: "Drivers: Systemd-Nspawn" -sidebar_current: "docs-drivers-community-nspawn" -description: |- - The Nspawn task driver is used to run application containers using Systemd-Nspawn. +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 From d93af4f449ece990ff36506b095df2dbee25386f Mon Sep 17 00:00:00 2001 From: JanMa Date: Sat, 29 Feb 2020 20:54:46 +0100 Subject: [PATCH 3/3] add missing sidebar item --- website/data/docs-navigation.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 441b5092f6b..2e72c5c0e2a 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' ] } ]