206 lines
6.8 KiB
Plaintext
206 lines
6.8 KiB
Plaintext
---
|
|
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` - The image to be used in the container. This can either be the path
|
|
to a
|
|
[directory](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-D),
|
|
the path to a file system
|
|
[image](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-i)
|
|
or block device or the name of an image registered with
|
|
[`systemd-machined`](https://www.freedesktop.org/software/systemd/man/systemd-machined.service.html).
|
|
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`](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
|
|
}
|
|
}
|
|
```
|
|
|
|
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`](https://www.freedesktop.org/software/systemd/man/machinectl.html#pull-tar%20URL%20%5BNAME%5D) -
|
|
(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][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][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][plugin] is
|
|
shown below:
|
|
|
|
```hcl
|
|
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`.
|
|
|
|
[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
|
|
[consul_connect_integration]: /docs/integrations/consul-connect
|