diff --git a/website/content/docs/devices/index.mdx b/website/content/docs/devices/index.mdx index 28c5e58893e..63fc9181717 100644 --- a/website/content/docs/devices/index.mdx +++ b/website/content/docs/devices/index.mdx @@ -1,18 +1,7 @@ --- layout: docs page_title: Device Plugins -description: Device Plugins are used to expose devices to tasks in Nomad. +description: Learn how device driver plugins expose devices such as GPUs USBs to tasks in Nomad jobs. --- -# Device Plugins - -Device plugins are used to detect and make devices available to tasks in -Nomad. Devices are physical hardware that exists on a client node such as a -GPU or an FPGA. By having extensible device plugins, Nomad has the flexibility -to support a broad set of devices and allows the community to build additional -device plugins as needed. - -The list of supported device plugins is provided on the left of this page. -Each device plugin documents its configuration and installation requirements, -the attributes it fingerprints, and the environment variables it exposes to -tasks. +@include 'device-driver-intro.mdx' diff --git a/website/content/docs/drivers/docker.mdx b/website/content/docs/drivers/docker.mdx index 881a66afd35..6011d717a73 100644 --- a/website/content/docs/drivers/docker.mdx +++ b/website/content/docs/drivers/docker.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Docker' -description: The Docker task driver is used to run Docker based tasks. +description: Learn how to configure and use Nomad's Docker task driver to run Docker-based tasks in your jobs. --- # Docker Driver diff --git a/website/content/docs/drivers/exec.mdx b/website/content/docs/drivers/exec.mdx index d399ee69b15..32e24fc77d6 100644 --- a/website/content/docs/drivers/exec.mdx +++ b/website/content/docs/drivers/exec.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Exec' -description: The Exec task driver runs binaries using OS isolation primitives. +description: Learn how to configure and use Nomad's Exec task driver in your jobs to run binaries using OS isolation primitives. --- # Isolated Fork/Exec Driver diff --git a/website/content/docs/drivers/index.mdx b/website/content/docs/drivers/index.mdx index 2ef4feff22d..f6188d7a226 100644 --- a/website/content/docs/drivers/index.mdx +++ b/website/content/docs/drivers/index.mdx @@ -1,41 +1,7 @@ --- layout: docs page_title: Task Drivers -description: Task Drivers are used to integrate with the host OS to run tasks in Nomad. +description: Learn how Nomad's bundled task drivers integrate with the host OS to run job tasks in isolation. --- -# Task Drivers - -Task drivers are used by Nomad clients to execute a task and provide resource -isolation. By having extensible task drivers, Nomad has the flexibility to -support a broad set of workloads across all major operating systems. - -Task drivers are pluggable. This gives you the flexibility to introduce your -own drivers without having to recompile Nomad. You can view the -[plugin block][plugin] documentation for examples on how to use the plugin -block in Nomad's client configuration. See the Docker driver's -[Client Requirements][docker_plugin] for a more detailed and specific example. - -The Nomad binary includes the default task drivers, so you do not have to -download them separately. - -The list of supported task drivers is provided on the left of this page. Each -task driver documents the configuration available in a [job -specification](/nomad/docs/job-specification), the environments it can be -used in, and the resource isolation mechanisms available. - -For details on authoring a task driver plugin, please refer to the [plugin -authoring guide][plugin_guide]. - -Task driver resource isolation is intended to provide a degree of separation of -Nomad client CPU / memory / storage between tasks. Resource isolation -effectiveness is dependent upon individual task driver implementations and -underlying client operating systems. Task drivers do include various -security-related controls, but the Nomad client to task interface should not be -considered a security boundary. See the [access control guide][acl_guide] for -more information on how to protect Nomad cluster operations. - -[plugin]: /nomad/docs/configuration/plugin -[docker_plugin]: /nomad/docs/drivers/docker#client-requirements -[plugin_guide]: /nomad/docs/concepts/plugins -[acl_guide]: /nomad/tutorials/access-control +@include 'task-driver-intro.mdx' diff --git a/website/content/docs/drivers/java.mdx b/website/content/docs/drivers/java.mdx index 58d8f3aae21..c128ca8dedb 100644 --- a/website/content/docs/drivers/java.mdx +++ b/website/content/docs/drivers/java.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Java' -description: The Java task driver is used to run Jars using the JVM. +description: Learn how to configure and use Nomad's Java task driver to run JAR files in your jobs. --- # Java Driver diff --git a/website/content/docs/drivers/qemu.mdx b/website/content/docs/drivers/qemu.mdx index 4a86628ff0e..e54008ab615 100644 --- a/website/content/docs/drivers/qemu.mdx +++ b/website/content/docs/drivers/qemu.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: QEMU' -description: The QEMU task driver is used to run virtual machines using QEMU/KVM. +description: Learn how to configure and use Nomad's QEMU task driver to run virtual machines using QEMU/KVM in your jobs. --- # QEMU Driver diff --git a/website/content/docs/drivers/raw_exec.mdx b/website/content/docs/drivers/raw_exec.mdx index 1e01a1e4e2e..55e658ca98a 100644 --- a/website/content/docs/drivers/raw_exec.mdx +++ b/website/content/docs/drivers/raw_exec.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Raw Exec' -description: The Raw Exec task driver simply fork/execs and provides no isolation. +description: Learn how to configure and use Nomad's Raw Exec task driver to execute commands without isolation in your jobs. --- # Raw Fork/Exec Driver diff --git a/website/content/partials/device-driver-intro.mdx b/website/content/partials/device-driver-intro.mdx new file mode 100644 index 00000000000..d233f42b72e --- /dev/null +++ b/website/content/partials/device-driver-intro.mdx @@ -0,0 +1,28 @@ + +# Device driver plugins + +Use device driver plugins to detect and make devices available to tasks in +Nomad jobs. Devices are physical hardware that exists on a client node such as a +GPU or an FPGA. By having extensible device plugins, Nomad has the flexibility +to support a broad set of devices and allows the community to build additional +device plugins as needed. + +## Nomad device drivers + +We support the [NVIDIA] device driver plugin, which you must install +separately. Refer to the [NVIDIA] documentation for instructions. + +## Community device drivers + +The community supports the [USB] device driver plugin. + +## Create device drivers + +Nomad's device driver architecture is pluggable, which gives you the flexibility +to create your own drivers without having to recompile Nomad. Refer to the +[plugin authoring guide][plugin_guide] for details. + + +[NVIDIA]: /nomad/plugins/devices/nvidia +[USB]: /nomad/plugins/devices/community/usb +[plugin_guide]: /nomad/docs/concepts/plugins/devices diff --git a/website/content/partials/task-driver-intro.mdx b/website/content/partials/task-driver-intro.mdx new file mode 100644 index 00000000000..cd708555ad0 --- /dev/null +++ b/website/content/partials/task-driver-intro.mdx @@ -0,0 +1,61 @@ +# Task drivers + +Nomad clients use task drivers to execute a task and provide resource isolation. +By having extensible task drivers, Nomad has the flexibility to support a broad +set of workloads across all major operating systems. + +Task driver resource isolation provides a degree of separation of Nomad client +CPU, memory, and storage between tasks. Resource isolation effectiveness depends +upon individual task driver implementations and underlying client operating +systems. Task drivers do include various security-related controls, but the +Nomad client-to-task interface should not be considered a security boundary. +Refer to the [access control guide][acl_guide] for more information on how to +protect Nomad cluster operations. + +## Configuration + +Refer to the [plugin block][plugin] documentation for examples on how to use the +plugin block in Nomad's client configuration. Review the Docker driver's [Client +Requirements][docker_plugin] section for a detailed example. + +## Nomad task drivers + +The Nomad binary contains several bundled task drivers. We also support +additional task drivers that you may install separately. + +| Bundled with Nomad | Separate installation | +|----------------------|-----------------------| +| [Docker] | [Exec2] | +| [Isolated Fork/Exec] | [Podman] | +| [Java] | [Virt] | +| [QEMU] | | +| [Raw Fork/Exec] | | + +Each task driver page documents the configuration available in a [job +specification](/nomad/docs/job-specification), the environments you can use the +task driver in, and the resource isolation mechanisms available. + +## Community task drivers + +You may also use [community-supported task driver +plugins](/nomad/plugins/drivers/community/). + +## Create task drivers + +Nomad's task driver architecture is pluggable, which gives you the flexibility +to create your own drivers without having to recompile Nomad. Refer to the +[plugin authoring guide][plugin_guide] for details. + + +[plugin]: /nomad/docs/configuration/plugin +[docker_plugin]: /nomad/docs/drivers/docker#client-requirements +[plugin_guide]: /nomad/docs/concepts/plugins/task-drivers +[acl_guide]: /nomad/tutorials/access-control +[Docker]: /nomad/docs/drivers/docker +[Exec2]: /nomad/plugins/drivers/exec2 +[Isolated Fork/Exec]: /nomad/docs/drivers/exec +[Podman]: /nomad/plugins/drivers/podman +[Java]: /nomad/docs/drivers/java +[Virt]: /nomad/plugins/drivers/virt/index +[QEMU]: /nomad/docs/drivers/qemu +[Raw Fork/Exec]: /nomad/docs/drivers/raw_exec diff --git a/website/content/plugins/devices/community/index.mdx b/website/content/plugins/devices/community/index.mdx index 6915b31e2db..155a481158a 100644 --- a/website/content/plugins/devices/community/index.mdx +++ b/website/content/plugins/devices/community/index.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Device Plugins: Community Supported' -description: 'A list of community supported Device Plugins.' +description: Learn about the community-supported device driver plugins that extend Nomad job features. --- # Community Supported @@ -11,7 +11,7 @@ broader Nomad community and you are committed to maintaining the plugin, please file a PR to add your plugin to this page. For details on authoring a device plugin, please refer to the [plugin authoring guide][plugin_guide]. -Below is a list of community-support task drivers you can use with Nomad: +The following is a list of community-support device drivers you can use with Nomad: - [USB][usb] diff --git a/website/content/plugins/devices/community/usb.mdx b/website/content/plugins/devices/community/usb.mdx index aadea20a2ad..6d7611b29eb 100644 --- a/website/content/plugins/devices/community/usb.mdx +++ b/website/content/plugins/devices/community/usb.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Devices: USB' -description: The USB Device Plugin detects and makes USB devices available to tasks +description: Use the USB Device Plugin to detect and use USB devices in Nomad jobs. --- # USB Device Plugin diff --git a/website/content/plugins/devices/index.mdx b/website/content/plugins/devices/index.mdx index f09be25310b..607e795c77f 100644 --- a/website/content/plugins/devices/index.mdx +++ b/website/content/plugins/devices/index.mdx @@ -1,17 +1,7 @@ --- layout: docs page_title: 'Device Plugins: External' -description: 'A list of external Device Plugins.' +description: Learn how device driver plugins extend Nomad functionality to run jobs on hardware such as GPUs and USBs. --- -# External Device Plugins - -Nomad has a plugin system for defining task drivers. External device driver -plugins will have the same user experience as built in devices. - -Below is a list of official external task drivers you can use with Nomad: - -- [Nvidia][nvidia] - -[plugin_guide]: /nomad/docs/concepts/plugins -[nvidia]: /nomad/plugins/devices/nvidia +@include 'device-driver-intro.mdx' diff --git a/website/content/plugins/devices/nvidia.mdx b/website/content/plugins/devices/nvidia.mdx index d2e7bf93018..ec8ac5c80b1 100644 --- a/website/content/plugins/devices/nvidia.mdx +++ b/website/content/plugins/devices/nvidia.mdx @@ -1,10 +1,10 @@ --- layout: docs page_title: 'Device Plugins: Nvidia' -description: The Nvidia Device Plugin detects and makes Nvidia devices available to tasks. +description: Use the NVIDIA device plugin to expose NVIDIA GPUs to Nomad so you can run jobs on GPU hardware. --- -# Nvidia GPU Device Plugin +# NVIDIA GPU Device Plugin Name: `nomad-device-nvidia` diff --git a/website/content/plugins/drivers/community/containerd.mdx b/website/content/plugins/drivers/community/containerd.mdx index 218df3e4fd6..d8f69ddb02a 100644 --- a/website/content/plugins/drivers/community/containerd.mdx +++ b/website/content/plugins/drivers/community/containerd.mdx @@ -2,8 +2,7 @@ layout: docs page_title: 'Drivers: nomad-driver-containerd' description: >- - The containerd driver is used - for launching containers using containerd. + Use the containerd task driver to launch containerd containers in your Nomad job. --- # containerd Task Driver diff --git a/website/content/plugins/drivers/community/firecracker-task-driver.mdx b/website/content/plugins/drivers/community/firecracker-task-driver.mdx index f0e33509226..01a216b2909 100644 --- a/website/content/plugins/drivers/community/firecracker-task-driver.mdx +++ b/website/content/plugins/drivers/community/firecracker-task-driver.mdx @@ -2,15 +2,14 @@ layout: docs page_title: 'Drivers: firecracker-task-driver' description: >- - The Firecracker task driver is used to run - firecracker(https://firecracker-microvm.github.io/) microvms. + Use the Firecracker task driver to run Firecracker micro virtual machines in your Nomad job. --- # Firecracker task Driver Name: `firecracker-task-driver` -The Firecracker task driver provides an interface for creating Linux microvms. +The Firecracker task driver provides an interface for creating Linux microVMs. For more detailed instructions on how to set up and use this driver, please refer to the [documentation][firecracker-task-guide]. diff --git a/website/content/plugins/drivers/community/iis.mdx b/website/content/plugins/drivers/community/iis.mdx index 3e4605ce349..90ac710d0bf 100644 --- a/website/content/plugins/drivers/community/iis.mdx +++ b/website/content/plugins/drivers/community/iis.mdx @@ -2,15 +2,14 @@ layout: docs page_title: 'Drivers: nomad-driver-iis' description: >- - The IIS driver is used for running - Windows IIS services. + Use the Windows IIS task driver to run Windows IIS services in Nomad jobs. --- # Windows IIS Driver Name: `win_iis` -The Nomad IIS driver provides an interface for running Windows IIS website tasks. +The Nomad `win_iis` task driver provides an interface for running Windows IIS website tasks. A "website" is a combination of an application pool and a site (app, vdir, etc.). Each allocation will create an application pool and site with the name being the allocation ID (guid). diff --git a/website/content/plugins/drivers/community/index.mdx b/website/content/plugins/drivers/community/index.mdx index 478da574c2a..44758385502 100644 --- a/website/content/plugins/drivers/community/index.mdx +++ b/website/content/plugins/drivers/community/index.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Task Driver Plugins: Community Supported' -description: A list of community supported Task Driver Plugins. +description: Learn about the community-supported task driver plugins that extend Nomad job features. --- # Community Supported @@ -18,7 +18,7 @@ authoring guide][plugin_guide]. Nomad has a plugin system for defining task drivers. External task driver plugins will have the same user experience as built in drivers. -Below is a list of community-supported task drivers you can use with Nomad: +The following is a list of community-supported task drivers you can use with Nomad: - [containerd][nomad-driver-containerd] - [Firecracker][firecracker-task-driver] @@ -29,8 +29,8 @@ Below is a list of community-supported task drivers you can use with Nomad: - [Rookout][rookout] - [Singularity][singularity] - [systemd-nspawn][nspawn-driver] -- [Windows IIS][nomad-driver-iis] -- [Windows IIS][nomad-iis] +- [Windows IIS (nomad-driver-iis)][nomad-driver-iis] +- [Windows IIS (nomad-iis)][nomad-iis] [rookout]: /nomad/plugins/drivers/community/rookout [plugin_guide]: /nomad/docs/concepts/plugins diff --git a/website/content/plugins/drivers/community/jail-task-driver.mdx b/website/content/plugins/drivers/community/jail-task-driver.mdx index 2954ce1b669..66e6aebb76d 100644 --- a/website/content/plugins/drivers/community/jail-task-driver.mdx +++ b/website/content/plugins/drivers/community/jail-task-driver.mdx @@ -2,8 +2,8 @@ layout: docs page_title: 'Drivers: jail-task-driver' description: >- - The Jail task driver is used to run application containers using FreeBSD - jails. + Use the Jail task driver to run application containers using FreeBSD + jails in your Nomad jobs. --- # Jail task Driver diff --git a/website/content/plugins/drivers/community/lightrun.mdx b/website/content/plugins/drivers/community/lightrun.mdx index e71ad18b5c4..f2c91f6b01c 100644 --- a/website/content/plugins/drivers/community/lightrun.mdx +++ b/website/content/plugins/drivers/community/lightrun.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Lightrun' -description: The Lightrun driver is used to run your Java application with Lightrun. +description: Use the Lightrun task driver to run your Java application with Lightrun in your Nomad jobs. --- # Lightrun Driver diff --git a/website/content/plugins/drivers/community/nomad-iis.mdx b/website/content/plugins/drivers/community/nomad-iis.mdx index a2514d92a44..832da144013 100644 --- a/website/content/plugins/drivers/community/nomad-iis.mdx +++ b/website/content/plugins/drivers/community/nomad-iis.mdx @@ -2,15 +2,14 @@ layout: docs page_title: 'Drivers: nomad-iis' description: >- - The IIS driver is used for running - Windows IIS services. + Use the Nomad IIS driver to run Windows IIS services in Nomad jobs. --- # Windows IIS Driver Name: `nomad_iis` -This plugin is a task driver to run IIS Web Applications on Windows Servers. Each allocation will create an AppPool and a Website. +The `nomad_iis` plugin is a task driver to run IIS Web Applications on Windows Servers. Each allocation will create an AppPool and a Website. For a full documentation please refer to the project's [Readme](https://github.com/sevensolutions/nomad-iis/blob/main/README.md). Unlike most other Nomad task drivers, this one is written in the C# language using ASP.NET. It uses the Microsoft.Web.Administration-API to communicate with IIS. @@ -28,7 +27,7 @@ job "iis-test" { group "iis-test" { count = 1 - + network { port "httplabel" {} } @@ -44,13 +43,13 @@ job "iis-test" { alias = "subapp" path = "C:\\inetpub\\wwwroot" } - + binding { type = "http" port = "httplabel" } } - + env { my_key = "my-value" } diff --git a/website/content/plugins/drivers/community/nspawn.mdx b/website/content/plugins/drivers/community/nspawn.mdx index 20d0c934830..b5878a3e583 100644 --- a/website/content/plugins/drivers/community/nspawn.mdx +++ b/website/content/plugins/drivers/community/nspawn.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: systemd-nspawn' -description: The nspawn task driver is used to run application containers using systemd-nspawn. +description: Use the nspawn task driver to run application containers using systemd-nspawn in Nomad jobs. --- # nspawn Driver diff --git a/website/content/plugins/drivers/community/pledge.mdx b/website/content/plugins/drivers/community/pledge.mdx index 93925d0309e..17e5c6f032f 100644 --- a/website/content/plugins/drivers/community/pledge.mdx +++ b/website/content/plugins/drivers/community/pledge.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Pledge' -description: The Pledge task driver is capable of blocking unwanted syscall and filesystem access. +description: Use the Pledge task driver to block unwanted syscall and filesystem access in Nomad jobs. --- # Pledge Driver diff --git a/website/content/plugins/drivers/community/pot.mdx b/website/content/plugins/drivers/community/pot.mdx index 0f227afd0fd..7e71ebc4f9a 100644 --- a/website/content/plugins/drivers/community/pot.mdx +++ b/website/content/plugins/drivers/community/pot.mdx @@ -2,8 +2,7 @@ layout: docs page_title: 'Drivers: pot' description: >- - The Pot task driver is used to run pot (https://github.com/pizzamig/pot) - containers using FreeBSD jails. + Use the Pot task driver to run pot containers using FreeBSD jails in Nomad jobs. --- # Pot Task Driver diff --git a/website/content/plugins/drivers/community/rookout.mdx b/website/content/plugins/drivers/community/rookout.mdx index 04e767ede34..8f165811cf7 100644 --- a/website/content/plugins/drivers/community/rookout.mdx +++ b/website/content/plugins/drivers/community/rookout.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Rookout' -description: The Rookout driver is used to run your Java app with Rookout. +description: Use the Rookout driver to run your Java app with Rookout in Nomad jobs. --- # Rookout Driver diff --git a/website/content/plugins/drivers/community/singularity.mdx b/website/content/plugins/drivers/community/singularity.mdx index f2cadd1e31c..b9987ad86b4 100644 --- a/website/content/plugins/drivers/community/singularity.mdx +++ b/website/content/plugins/drivers/community/singularity.mdx @@ -2,8 +2,8 @@ layout: docs page_title: 'Drivers: Singularity' description: >- - The Singularity task driver is used to run application containers using - Singularity. + Use the Singularity task driver to run application containers using + Singularity in Nomad jobs. --- # Singularity Driver diff --git a/website/content/plugins/drivers/exec2.mdx b/website/content/plugins/drivers/exec2.mdx index 14830870641..8a84faf0e65 100644 --- a/website/content/plugins/drivers/exec2.mdx +++ b/website/content/plugins/drivers/exec2.mdx @@ -2,7 +2,7 @@ layout: docs page_title: 'Drivers: exec2' description: >- - The exec2 task driver leverages modern kernel features for constraining tasks. + Learn how to configure and use the exec2 task driver to leverage kernel features such as landlock, cgroups, and unshare to constrain job tasks. --- # Exec2 Task Driver diff --git a/website/content/plugins/drivers/index.mdx b/website/content/plugins/drivers/index.mdx index 2ef4feff22d..a299ad9ac56 100644 --- a/website/content/plugins/drivers/index.mdx +++ b/website/content/plugins/drivers/index.mdx @@ -1,41 +1,8 @@ --- layout: docs page_title: Task Drivers -description: Task Drivers are used to integrate with the host OS to run tasks in Nomad. +description: Learn how task driver plugins extend Nomad functionality to provide resource isolation when executing job tasks. --- -# Task Drivers +@include 'task-driver-intro.mdx' -Task drivers are used by Nomad clients to execute a task and provide resource -isolation. By having extensible task drivers, Nomad has the flexibility to -support a broad set of workloads across all major operating systems. - -Task drivers are pluggable. This gives you the flexibility to introduce your -own drivers without having to recompile Nomad. You can view the -[plugin block][plugin] documentation for examples on how to use the plugin -block in Nomad's client configuration. See the Docker driver's -[Client Requirements][docker_plugin] for a more detailed and specific example. - -The Nomad binary includes the default task drivers, so you do not have to -download them separately. - -The list of supported task drivers is provided on the left of this page. Each -task driver documents the configuration available in a [job -specification](/nomad/docs/job-specification), the environments it can be -used in, and the resource isolation mechanisms available. - -For details on authoring a task driver plugin, please refer to the [plugin -authoring guide][plugin_guide]. - -Task driver resource isolation is intended to provide a degree of separation of -Nomad client CPU / memory / storage between tasks. Resource isolation -effectiveness is dependent upon individual task driver implementations and -underlying client operating systems. Task drivers do include various -security-related controls, but the Nomad client to task interface should not be -considered a security boundary. See the [access control guide][acl_guide] for -more information on how to protect Nomad cluster operations. - -[plugin]: /nomad/docs/configuration/plugin -[docker_plugin]: /nomad/docs/drivers/docker#client-requirements -[plugin_guide]: /nomad/docs/concepts/plugins -[acl_guide]: /nomad/tutorials/access-control diff --git a/website/content/plugins/drivers/podman.mdx b/website/content/plugins/drivers/podman.mdx index 6e23f5d1ab7..98df75184a3 100644 --- a/website/content/plugins/drivers/podman.mdx +++ b/website/content/plugins/drivers/podman.mdx @@ -2,8 +2,7 @@ layout: docs page_title: 'Drivers: podman' description: >- - The Podman task driver uses podman (https://podman.io/) for containerizing - tasks. + Learn how to configure and use the Podman container runtime to execute your Nomad job tasks. --- # Podman Task Driver diff --git a/website/content/plugins/drivers/virt/client.mdx b/website/content/plugins/drivers/virt/client.mdx deleted file mode 100644 index 8c26ef8ab4c..00000000000 --- a/website/content/plugins/drivers/virt/client.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -layout: docs -page_title: Client -description: Nomad client requirements, capabilities, and configuration options for the Virt task driver. ---- - -# Client - -@include 'virt-beta-callout.mdx' - -The `virt` task driver is not built into Nomad. You must [downloaded][releases] onto the client -host in the configured plugin directory. The client host must also be capable of running hardware -accelerated KVM virtual machines, which you can check by using [kvm-ok][] command. -Additional requirements: - -- Linux -- Commands `bridge-utils`, `cloudinit`, `dnsmasq`, and `iptables` -- [libvirt daemon][] installed and running -- QEMU system packages installed -- Nomad client running as root - -Use the following command to install the package requirements: - -```console -$ sudo apt-get update && \ - sudo apt-get install -y \ - bridge-utils \ - cloud-init \ - dnsmasq \ - iptables \ - libvirt-daemon-system \ - qemu-system \ - qemu-system-x86 \ - qemu-utils -``` - -## Client capabilities - -The `virt` task driver implements the following driver [capabilities][capabilities]. - -| Feature | Implementation | -|----------------------|----------------| -| `nomad alloc signal` | false | -| `nomad alloc exec` | false | -| filesystem isolation | image | -| network isolation | host | -| volume mounting | false | - -## Plugin configuration - -This example shows the default plugin configuration. - -```hcl -plugin "nomad-driver-driver" { - config { - data_dir = "/var/lib/virt" - image_paths = ["/var/lib/virt", "${ALLOC_DIR}"] - - emulator { - uri = "qemu:///system" - user = "" - password = "" - } - } -} -``` - -- `data_dir` - (default: `"/var/lib/virt"`) - the directory for storing VM configuration files and - intermediate files. - -- `image_paths` - (default: `["/var/lib/virt", "${ALLOC_DIR}"]`) - an allow-list of paths the driver - is allowed to load an image from. - -- `emulator` - (block) - - `uri` - (default: `"qemu:///system"`) - The `uri` specifies which hypervisor to connect to. - - `user` - (default: `""`) - the username to use for authentication. - - `password` - (default: `""`) - the password to use for authentication. - -## Client attributes - -When installed, the `virt` plugin provides the following node attributes that you can use as -constraints when authoring jobs. - -``` -driver.virt = true -driver.virt.active = 0 -driver.virt.emulator.version = 8002002 -driver.virt.inactive = 0bytes -driver.virt.libvirt.version = 10000000 -driver.virt.network.default.bridge_name = virbr0 -driver.virt.network.default.state = active -``` - -[releases]: https://releases.hashicorp.com/nomad-driver-virt -[kvm-ok]: https://manpages.ubuntu.com/manpages/bionic/man1/kvm-ok.1.html -[libvirt daemon]: https://libvirt.org/daemons.html -[capabilities]: https://developer.hashicorp.com/nomad/docs/concepts/plugins/task-drivers#task-driver-plugin-api diff --git a/website/content/plugins/drivers/virt/index.mdx b/website/content/plugins/drivers/virt/index.mdx index f9df33da750..2ae708a343b 100644 --- a/website/content/plugins/drivers/virt/index.mdx +++ b/website/content/plugins/drivers/virt/index.mdx @@ -2,8 +2,7 @@ layout: docs page_title: 'Drivers: virt' description: >- - The virt task driver leverages Linux capabilities and libvirt to run virtual - machines. + Use the Virt task driver in your Nomad jobs to leverage Linux capabilities and to run virtual machines using the libvirt API. Learn about Nomad client requirements, installation, capabilities, and attributes. --- # Virt task driver @@ -12,9 +11,42 @@ description: >- Name: `virt` -The `virt` driver utilises the [libvirt][] API to run and manage virtual machines (VMs) via -hypervisors such as [QEMU][]. It supports a wide variety of Nomad features including -[workload identity][], [task templates][], and [service discovery][]. +The Virt task driver utilizes the [libvirt][] API to run and manage virtual +machines using hypervisors such as [QEMU][]. The task driver supports a wide +variety of Nomad features including [workload identity][], [task templates][], +and [service discovery][]. + +## Driver capabilities + +The Virt task driver implements these driver [capabilities][capabilities]. + +| Feature | Implementation | +|----------------------|----------------| +| `nomad alloc signal` | false | +| `nomad alloc exec` | false | +| filesystem isolation | image | +| network isolation | host | +| volume mounting | false | + +## Nomad client node attributes + +The Virt task driver provides these node attributes that you can use as +constraints when authoring jobs. + +``` +driver.virt = true +driver.virt.active = 0 +driver.virt.emulator.version = 8002002 +driver.virt.inactive = 0bytes +driver.virt.libvirt.version = 10000000 +driver.virt.network.default.bridge_name = virbr0 +driver.virt.network.default.state = active +``` + +## Reference + +- [Install and configure the Virt task driver][install]. +- [Configure a virt task in your job specification][task-config]. [libvirt]: https://libvirt.org/ @@ -23,3 +55,6 @@ hypervisors such as [QEMU][]. It supports a wide variety of Nomad features inclu [task templates]: https://developer.hashicorp.com/nomad/docs/job-specification/template [service discovery]: https://developer.hashicorp.com/nomad/docs/networking/service-discovery [github]: https://github.com/hashicorp/nomad-driver-virt +[capabilities]: /nomad/docs/concepts/plugins/task-drivers#task-driver-plugin-api +[install]: /nomad/plugins/drivers/virt/install +[task-config]: /nomad/plugins/drivers/virt/task-config diff --git a/website/content/plugins/drivers/virt/install.mdx b/website/content/plugins/drivers/virt/install.mdx new file mode 100644 index 00000000000..5b42e207ee6 --- /dev/null +++ b/website/content/plugins/drivers/virt/install.mdx @@ -0,0 +1,148 @@ +--- +layout: docs +page_title: Install and configure the Virt task driver +description: >- + Install and configure the Virt task driver on your Nomad client. +--- + +# Install and configure the Virt task driver + +@include 'virt-beta-callout.mdx' + +The Virt task driver plugin for Linux operating systems is not bundled with +Nomad. You must install the driver into each Nomad client's [configured plugin +directory][plugin_dir]. + +Your Nomad client must meet these requirements: + +- Run as root. +- Able to run hardware-accelerated KVM virtual machines. Run the [kvm-ok][] + command to verify your client capabilities. + +The Virt driver requires the following packages: + +- bridge-utils +- cloudinit +- dnsmasq +- iptables +- [libvirt daemon][] +- [QEMU][] + +## Install the Virt driver + + + + +Download a [precompiled binary][releases] and verify the binary using the +available SHA-256 sums. Unzip the package. Make sure that the +`nomad-driver-virt` binary is on your +[plugin_dir] path, specified by the +client's config file, before continuing with the other guides. + + + + +Install the required packages. + +```shell-session +$ sudo apt-get update && \ + sudo apt-get install -y \ + wget \ + gpg \ + coreutils \ + bridge-utils \ + cloud-init \ + dnsmasq \ + iptables \ + libvirt-daemon-system \ + qemu-system \ + qemu-system-x86 \ + qemu-utils +``` + +Add the HashiCorp [GPG key][gpg-key]. + +```shell-session +$ wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg +``` + +Add the official HashiCorp Linux test repository. + +```shell-session +$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) test" | sudo tee /etc/apt/sources.list.d/hashicorp.list +``` + +Update and install. + +```shell-session +$ sudo apt-get update && sudo apt-get install nomad-driver-virt +``` + + + + +Install `yum-config-manager` to manage your repositories. + +```shell-session +$ sudo yum install -y yum-utils +``` + +Use `yum-config-manager` to add the official HashiCorp Linux repository. + +```shell-session +$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo +``` + +Edit the repo file at `/etc/yum.repos.d/hashicorp.repo` and set `enabled=1` for `[hashicorp-test]`. + +Install. + +```shell-session +$ sudo yum -y install nomad-driver-virt +``` + + + + + + +## Configure the Virt driver as a plugin + +This example shows the default plugin configuration. + +```hcl +plugin "nomad-driver-driver" { + config { + data_dir = "/var/lib/virt" + image_paths = ["/var/lib/virt", "${ALLOC_DIR}"] + + emulator { + uri = "qemu:///system" + user = "" + password = "" + } + } +} +``` + +- `data_dir` - (default: `"/var/lib/virt"`) - the directory for storing VM configuration files and + intermediate files. + +- `image_paths` - (default: `["/var/lib/virt", "${ALLOC_DIR}"]`) - an allow-list of paths the driver + is allowed to load an image from. + +- `emulator` - (block) + - `uri` - (default: `"qemu:///system"`) - The `uri` specifies which hypervisor to connect to. + - `user` - (default: `""`) - the username to use for authentication. + - `password` - (default: `""`) - the password to use for authentication. + +## Next steps + +[Learn how to use the Virt task driver in your Nomad job specification][task-config]. + +[releases]: https://releases.hashicorp.com/nomad-driver-virt +[kvm-ok]: https://manpages.ubuntu.com/manpages/bionic/man1/kvm-ok.1.html +[libvirt daemon]: https://libvirt.org/daemons.html +[QEMU]: https://www.qemu.org/ +[task-config]: /nomad/plugins/drivers/virt/task-config +[plugin_dir]: /nomad/docs/configuration#plugin_dir diff --git a/website/content/plugins/drivers/virt/installation.mdx b/website/content/plugins/drivers/virt/installation.mdx deleted file mode 100644 index 9628cc780c5..00000000000 --- a/website/content/plugins/drivers/virt/installation.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -layout: docs -page_title: Installation -description: Installation of the virt task driver. ---- - -# Installation - -@include 'virt-beta-callout.mdx' - -Use the following instructions to download the task driver for use on your Nomad client host. - - - - - Download a [precompiled binary](https://releases.hashicorp.com/nomad-driver-virt/) and - verify the binary using the available SHA-256 sums. Unzip the package. Make sure that the `nomad-driver-virt` binary is on your - [plugin_dir](/nomad/docs/configuration#plugin_dir) path, specified by the client's config file, - before continuing with the other guides. - - - - - Install the required packages. - - ```shell-session - $ sudo apt-get update && \ - sudo apt-get install wget gpg coreutils - ``` - - Add the HashiCorp [GPG key][gpg-key]. - - ```shell-session - $ wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg - ``` - - Add the official HashiCorp Linux test repository. - - ```shell-session - $ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) test" | sudo tee /etc/apt/sources.list.d/hashicorp.list - ``` - - Update and install. - - ```shell-session - $ sudo apt-get update && sudo apt-get install nomad-driver-virt - ``` - - - - - Install `yum-config-manager` to manage your repositories. - - ```shell-session - $ sudo yum install -y yum-utils - ``` - - Use `yum-config-manager` to add the official HashiCorp Linux repository. - - ```shell-session - $ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo - ``` - - Edit the repo file at `/etc/yum.repos.d/hashicorp.repo` and set `enabled=1` for `[hashicorp-test]`. - - Install. - - ```shell-session - $ sudo yum -y install nomad-driver-virt - ``` - - - diff --git a/website/content/plugins/drivers/virt/task-config.mdx b/website/content/plugins/drivers/virt/task-config.mdx index e40b0599386..dc87d6cd80f 100644 --- a/website/content/plugins/drivers/virt/task-config.mdx +++ b/website/content/plugins/drivers/virt/task-config.mdx @@ -1,14 +1,16 @@ --- layout: docs -page_title: Task Config -description: Configure the virt task driver job specification parameters. +page_title: Configure a virt job task +description: Learn how to use the Virt task driver in your Nomad job specification. Configure a base VM image and set parameters for bootstrapping the VM instance. --- -# Task configuration +# Configure a virt job task @include 'virt-beta-callout.mdx' -Task configuration for an virt task includes setting an `image` to provide the base VM image as +## Parameters + +Task configuration for a virt task includes setting an `image` to provide the base VM image as well as other parameters required for bootstrapping a VM instance. - `image` - (string: required) - Path to an `.img` cloud image to base the VM disk on. The image should @@ -50,7 +52,7 @@ config { } ``` -##### os +### os The VM architecture and machine can be different from the client host. When this is the case, you must set the `os` block. By default, this information matches the client host where the driver @@ -70,7 +72,7 @@ config { } ``` -##### network_interface +### network_interface You need to attach tasks to a libvirt network in order to access the internet and route from the local network. The `network_interface` block enables this as a list of network interfaces @@ -97,7 +99,7 @@ config { } ``` -### Full example +## Example configuration The following job specification displays use of all the configuration options, as well as other blocks that are useful when deploying tasks via the virt driver. You need to modify parameters, such as the diff --git a/website/content/plugins/index.mdx b/website/content/plugins/index.mdx index 817495908f4..8df8c9ce475 100644 --- a/website/content/plugins/index.mdx +++ b/website/content/plugins/index.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Plugins -description: Learn about task driver and device plugins for Nomad. +description: Learn how to use task driver and device plugins in your Nomad jobs. --- # Plugins diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e8f2d97aa67..ab948e5df74 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -2007,11 +2007,7 @@ }, { "title": "Installation", - "href": "/plugins/drivers/virt/installation" - }, - { - "title": "Client", - "href": "/plugins/drivers/virt/client" + "href": "/plugins/drivers/virt/install" }, { "title": "Task Config", diff --git a/website/data/plugins-nav-data.json b/website/data/plugins-nav-data.json index 035cebaffb1..0e40699b4a6 100644 --- a/website/data/plugins-nav-data.json +++ b/website/data/plugins-nav-data.json @@ -22,12 +22,8 @@ "path": "drivers/virt" }, { - "title": "Installation", - "path": "drivers/virt/installation" - }, - { - "title": "Client", - "path": "drivers/virt/client" + "title": "Install", + "path": "drivers/virt/install" }, { "title": "Task Config",