mirror of
https://github.com/kemko/nomad.git
synced 2026-01-05 09:55:44 +03:00
6dbc3a29c7
There have been some new config options added in recent releases of the nspawn driver. This commit updates the docs accordingly.
183 lines
6.8 KiB
Plaintext
183 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
|