From 3ba16e67fb5d4ed54b499d8b2b1f7caef31ba48b Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Mon, 19 May 2025 13:37:46 -0500 Subject: [PATCH 1/2] Docs: Point community plugins links to their docs/repos --- .../plugins/drivers/community/containerd.mdx | 423 ------------------ .../community/firecracker-task-driver.mdx | 130 ------ .../content/plugins/drivers/community/iis.mdx | 104 ----- .../plugins/drivers/community/index.mdx | 46 +- .../drivers/community/jail-task-driver.mdx | 148 ------ .../plugins/drivers/community/lightrun.mdx | 79 ---- .../plugins/drivers/community/nomad-iis.mdx | 74 --- .../plugins/drivers/community/nspawn.mdx | 204 --------- .../plugins/drivers/community/pledge.mdx | 332 -------------- .../content/plugins/drivers/community/pot.mdx | 100 ----- .../plugins/drivers/community/rookout.mdx | 52 --- .../plugins/drivers/community/singularity.mdx | 185 -------- website/data/plugins-nav-data.json | 24 +- website/redirects.js | 55 +++ 14 files changed, 76 insertions(+), 1880 deletions(-) delete mode 100644 website/content/plugins/drivers/community/containerd.mdx delete mode 100644 website/content/plugins/drivers/community/firecracker-task-driver.mdx delete mode 100644 website/content/plugins/drivers/community/iis.mdx delete mode 100644 website/content/plugins/drivers/community/jail-task-driver.mdx delete mode 100644 website/content/plugins/drivers/community/lightrun.mdx delete mode 100644 website/content/plugins/drivers/community/nomad-iis.mdx delete mode 100644 website/content/plugins/drivers/community/nspawn.mdx delete mode 100644 website/content/plugins/drivers/community/pledge.mdx delete mode 100644 website/content/plugins/drivers/community/pot.mdx delete mode 100644 website/content/plugins/drivers/community/rookout.mdx delete mode 100644 website/content/plugins/drivers/community/singularity.mdx diff --git a/website/content/plugins/drivers/community/containerd.mdx b/website/content/plugins/drivers/community/containerd.mdx deleted file mode 100644 index a735028a67c..00000000000 --- a/website/content/plugins/drivers/community/containerd.mdx +++ /dev/null @@ -1,423 +0,0 @@ ---- -layout: docs -page_title: Task driver plugin for containerd -description: >- - Use the community-supported containerd task driver to launch containerd containers in your Nomad job. ---- - -# containerd Task Driver Plugin - -Name: `containerd-driver` - -Homepage: https://github.com/Roblox/nomad-driver-containerd - -containerd ([`containerd.io`](https://containerd.io)) is a lightweight container -daemon for running and managing container lifecycle. Docker daemon also uses -containerd. - -```hcl -dockerd (docker daemon) --> containerd --> containerd-shim --> runc -``` - -`nomad-driver-containerd` enables Nomad clients to launch containers directly -using containerd, without Docker. The Docker daemon is therefore not required on -the host system. - -See the [project's homepage](https://github.com/Roblox/nomad-driver-containerd) -for more details. - -## Client Requirements - -The containerd task driver is not built into Nomad. It must be -[`downloaded`][releases] onto the client host in the configured plugin -directory. - -- Linux (Ubuntu >=16.04) with [`containerd`](https://containerd.io/downloads/) (>=1.3) installed. - -- [`containerd-driver`][releases] binary in Nomad's [plugin_dir][]. - -## Capabilities - -The `containerd-driver` implements the following [capabilities](/nomad/docs/concepts/plugins/task-drivers#capabilities-capabilities-error). - -| Feature | Implementation | -| -------------------- | ----------------------- | -| send signals | true | -| exec | true | -| filesystem isolation | image | -| network isolation | host, group, task, none | -| volume mounting | true | - -For sending signals, one can use `nomad alloc signal` command.
-For exec'ing into the container, one can use `nomad alloc exec` command. - -## Task Configuration - -Since Docker also relies on containerd for managing container lifecycle, the -example job created by [`nomad init -short`][nomad-init] can easily be adapted -to use `containerd-driver` instead: - -```hcl -job "redis" { - datacenters = ["dc1"] - - group "redis-group" { - task "redis-task" { - driver = "containerd-driver" - - config { - image = "docker.io/library/redis:alpine" - } - - resources { - cpu = 500 - memory = 256 - } - } - } -} -``` - -The containerd task driver supports the following parameters: - -- `image` - (Required) OCI image (Docker is also OCI compatible) for your - container. - -```hcl -config { - image = "docker.io/library/redis:alpine" -} -``` - -- `image_pull_timeout` - (Optional) A time duration that controls how long - `containerd-driver` will wait before cancelling an in-progress pull of the - OCI image as specified in `image`. Defaults to `"5m"`. - -- `command` - (Optional) Command to override command defined in the image. - -```hcl -config { - command = "some-command" -} -``` - -- `args` - (Optional) Arguments to the command. - -```hcl -config { - args = [ - "arg1", - "arg2", - ] -} -``` - -- `auth` - (Optional) Provide authentication for a private registry (See [Authentication] below). - -- `entrypoint` - (Optional) A string list overriding the image's entrypoint. - -- `cwd` - (Optional) Specify the current working directory (cwd) for your container process. - If the directory does not exist, one will be created for you. - -- `privileged` - (Optional) `true` or `false` (default) Run container in - privileged mode. Your container will have all Linux capabilities when running - in privileged mode. - -```hcl -config { - privileged = true -} -``` - -- `pids_limit` - (Optional) An integer value that specifies the pid limit for - the container. Defaults to unlimited. - -- `pid_mode` - (Optional) `host` or not set (default). Set to `host` to share - the PID namespace with the host. - -- `host_dns` - (Optional) `true` (default) or `false` By default, a container - launched using `containerd-driver` will use host `/etc/resolv.conf`. This is - similar to [Docker's behavior]. However, if you don't want to use - host DNS, you can turn off this flag by setting `host_dns=false`. - -- `seccomp` - (Optional) Enable default seccomp profile. List of [allowed syscalls]. - -- `seccomp_profile` - (Optional) Path to custom seccomp profile. - `seccomp` must be set to `true` in order to use `seccomp_profile`. - - The default `docker` seccomp profile found in the [Moby repository] - can be downloaded, and modified (by removing/adding syscalls) to create a custom seccomp profile. - The custom seccomp profile can then be saved under `/opt/seccomp/seccomp.json` on the Nomad client nodes. - -```hcl -config { - seccomp = true - seccomp_profile = "/opt/seccomp/seccomp.json" -} -``` - -- `shm_size` - (Optional) Size of /dev/shm e.g. `128M` if you want 128 MB of /dev/shm. - -- `sysctl` - (Optional) A key-value map of sysctl configurations to set to the - containers on start. - -```hcl - config { - sysctl = { - "net.core.somaxconn" = "16384" - "net.ipv4.ip_forward" = "1" - } - } -``` - -- `readonly_rootfs` - (Optional) `true` or `false` (default) Container root - filesystem will be read-only. - -```hcl -config { - readonly_rootfs = true -} -``` - -- `host_network` ((#host_network)) - (Optional) `true` or `false` (default) - Enable host network. This is equivalent to `--net=host` in docker. - -```hcl -config { - host_network = true -} -``` - -- `extra_hosts` - (Optional) A list of hosts, given as host:IP, to be added to - `/etc/hosts`. - -- `hostname` - (Optional) The hostname to assign to the container. When - launching more than one of a task (using `count`) with this option set, every - container the task starts will have the same hostname. - -- `cap_add` - (Optional) Add individual capabilities. - -```hcl -config { - cap_add = [ - "CAP_SYS_ADMIN", - "CAP_CHOWN", - "CAP_SYS_CHROOT" - ] -} -``` - -- `cap_drop` - (Optional) Drop individual capabilities. - -```hcl -config { - cap_drop = [ - "CAP_SYS_ADMIN", - "CAP_CHOWN", - "CAP_SYS_CHROOT" - ] -} -``` - -- `devices` - (Optional) A list of devices to be exposed to the container. - -```hcl -config { - devices = [ - "/dev/loop0", - "/dev/loop1" - ] -} -``` - -- `mounts` - (Optional) A list of mounts to be mounted in the container. Volume, - bind and tmpfs type mounts are supported. fstab style [`mount options`][] are - supported. - - - `type` - (Optional) Supported values are `volume`, `bind` or `tmpfs`. - **Default:** `volume`. - - - `target` - (Required) Target path in the container. - - - `source` - (Optional) Source path on the host. - - - `options` - (Optional) fstab style [`mount options`][]. **NOTE:** For bind - mounts, at least `rbind` and `ro` are required. - -```hcl -config { - mounts = [ - { - type = "bind" - target = "/tmp/t1" - source = "/tmp/s1" - options = ["rbind", "ro"] - } - ] -} -``` - -## Networking - -`nomad-driver-containerd` supports **host** and **bridge** networks. - -**NOTE:** `host` and `bridge` are mutually exclusive options, and only one of -them should be used at a time. - -1. **Host** network can be enabled by setting `host_network` to `true` in task - config of the job spec (see [host_network][host-network] under Task - Configuration). - -2. **Bridge** network can be enabled by setting the `network` block in the task - group section of the job spec. - -```hcl -network { - mode = "bridge" -} -``` - -You need to install CNI plugins on Nomad client nodes under `/opt/cni/bin` -before you can use `bridge` networks. - -**Instructions for installing CNI plugins.** - -```hcl - $ curl -L -o cni-plugins.tgz "https://github.com/containernetworking/plugins/releases/download/v1.0.0/cni-plugins-linux-$( [ $(uname -m) = aarch64 ] && echo arm64 || echo amd64)"-v1.0.0.tgz - $ sudo mkdir -p /opt/cni/bin - $ sudo tar -C /opt/cni/bin -xzf cni-plugins.tgz -``` - -Also, ensure your Linux operating system distribution has been configured -to allow container traffic through the bridge network to be routed via iptables. -These tunables can be set as follows: - -```hcl - $ echo 1 > /proc/sys/net/bridge/bridge-nf-call-arptables - $ echo 1 > /proc/sys/net/bridge/bridge-nf-call-ip6tables - $ echo 1 > /proc/sys/net/bridge/bridge-nf-call-iptables -``` - -To preserve these settings on startup of a Nomad client node, add a file -including the following to `/etc/sysctl.d/` or remove the file your Linux -distribution puts in that directory. - -```hcl - net.bridge.bridge-nf-call-arptables = 1 - net.bridge.bridge-nf-call-ip6tables = 1 - net.bridge.bridge-nf-call-iptables = 1 -``` - -## Port Forwarding - -Nomad supports both `static` and `dynamic` port mapping. - -1. **Static ports** - -Static port mapping can be added in the `network` block. - -```hcl -network { - mode = "bridge" - port "lb" { - static = 8889 - to = 8889 - } -} -``` - -Here, `host` port `8889` is mapped to `container` port `8889`.
-**NOTE:** static ports are usually not recommended, except for -`system` or specialized jobs like load balancers. - -2. **Dynamic ports** - -Dynamic port mapping is also enabled in the `network` block. - -```hcl -network { - mode = "bridge" - port "http" { - to = 8080 - } -} -``` - -Here, nomad will allocate a dynamic port on the `host` and that port -will be mapped to `8080` in the container. - -You can read more about configuring networking under the [`network`] block documentation. - -## Service discovery - -Nomad schedules workloads of various types across a cluster of generic hosts. -Because of this, placement is not known in advance and you will need to use -service discovery to connect tasks to other services deployed across your cluster. -Nomad integrates with Consul to provide service discovery and monitoring. - -A [`service`] block can be added to your job spec, to enable service discovery. - -The service block instructs Nomad to register a service with Consul. - -## Authentication ((#authentication)) - -`auth` block allow you to set credentials for your private registry e.g. if you want -to pull an image from a private repository in docker hub. -`auth` block can be set either in `Driver Config` or `Task Config` or both. -If set at both places, `Task Config` auth will take precedence over `Driver Config` auth. - -**NOTE**: In the below example, `user` and `pass` are just placeholder values which need to be -replaced by actual `username` and `password`, when specifying the credentials. Below `auth` -block can be used for both `Driver Config` and `Task Config`. - -```hcl -auth { - username = "user" - password = "pass" -} -``` - -## Plugin Options ((#plugin_options)) - -- `enabled` - (Optional) The `containerd` driver may be disabled on hosts by - setting this option to `false` (defaults to `true`). - -- `containerd_runtime` - (Required) Runtime for `containerd` e.g. - `io.containerd.runc.v1` or `io.containerd.runc.v2` - -- `stats_interval` - (Optional) This value defines how frequently you want to - send `TaskStats` to nomad client. (defaults to `1 second`). - -- `allow_privileged` - (Optional) If set to `false`, driver will deny running - privileged jobs. (defaults to `true`). - -An example of using these plugin options with the new [plugin syntax][plugin] is -shown below: - -```hcl -plugin "containerd-driver" { - config { - enabled = true - containerd_runtime = "io.containerd.runc.v2" - stats_interval = "5s" - } -} -``` - -Please note the plugin name should match whatever name you have specified for -the external driver in the [plugin_dir][plugin_dir] directory. - -[nomad-driver-containerd]: https://github.com/Roblox/nomad-driver-containerd -[nomad-init]: /nomad/docs/commands/job/init -[plugin]: /nomad/docs/configuration/plugin -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[plugin-options]: #plugin_options -[authentication]: #authentication -[host-network]: #host_network -[`mount options`]: https://github.com/containerd/containerd/blob/9561d9389d3dd87ff6030bf1da4e705bbc024130/mount/mount_linux.go#L198-L222 -[moby repository]: https://github.com/moby/moby/blob/master/profiles/seccomp/default.json -[docker's behavior]: https://docs.docker.com/config/containers/container-networking/#dns-services -[allowed syscalls]: https://github.com/containerd/containerd/blob/master/contrib/seccomp/seccomp_default.go#L51-L390 -[`network`]: /nomad/docs/job-specification/network -[`service`]: /nomad/docs/job-specification/service -[releases]: https://github.com/Roblox/nomad-driver-containerd/releases/ diff --git a/website/content/plugins/drivers/community/firecracker-task-driver.mdx b/website/content/plugins/drivers/community/firecracker-task-driver.mdx deleted file mode 100644 index 1869f69d903..00000000000 --- a/website/content/plugins/drivers/community/firecracker-task-driver.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -layout: docs -page_title: Firecracker task driver plugin -description: >- - Use the community-supported Firecracker task driver to run Firecracker micro virtual machines in your Nomad job. ---- - -# Firecracker task driver plugin - -Name: `firecracker-task-driver` - -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]. - -## Task Configuration - -```hcl -task "test01" { - driver = "firecracker-task-driver" - - config { - KernelImage = "/home/build/hello-vmlinux.bin" - Firecracker = "/home/build/firecracker" - Vcpus = 1 - Mem = 128 - Network = "default" - } -} -``` - -The firecracker task driver supports the following parameters: - -- `KernelImage` - (Optional) Path to the kernel image to be used on the microvm. - Defaults to 'vmlinux' in the [allocation working directory]. - -- `BootDisk` - (Optional) Path to the ext4 rootfs to boot from. - Defaults to 'rootfs.ext4' in the [allocation working directory]. - -- `BootOptions` - (Optional) Kernel command line options to boot the microvm. - Defaults to "ro console=ttyS0 reboot=k panic=1 pci=off" - -- `Network` - (Optional) Network name of your container network configuration - file. - -- `Vcpus` - (Optional) Number of CPUs to assign to microvm. - -- `Cputype` - (Optional) CPU template to use, templates available are C3 or T2. - -- `Mem` - (Optional) Amount of memory in Megabytes to assign to microvm. - Defaults to 512 - -- `Firecracker` Location of the firecracker binary, the option could be omitted - if the environment variable FIRECRACKER_BIN is setup. Defaults to - '/usr/bin/firecracker' - -- `DisableHt` - (Optional) Disable CPU Hyperthreading. Defaults to false - -- `Log` - (Optional) path to file where to write firecracker logs. - -## Networking - -Network configuration is setup using CNI plugins, the steps to setup firecracker -task driver with cni are the following: - -- Build [cni plugins][container network plugins] and [tc-redirect-tap][tc-redirect-tap] - and copy them to `/opt/cni`. - -- Create a network configuration to be used by micro-vms on /etc/cni/conf.d/, - for example: default.conflist. - -### Example network configuration - -```json -{ - "name": "default", - "cniVersion": "0.4.0", - "plugins": [ - { - "type": "ptp", - "ipMasq": true, - "ipam": { - "type": "host-local", - "subnet": "192.168.127.0/24", - "resolvConf": "/etc/resolv.conf" - } - }, - { - "type": "firewall" - }, - { - "type": "tc-redirect-tap" - } - ] -} -``` - -In this example the name of this network is default and this name is the -parameter used in Network on the task driver job spec. Also the filename must -match the name of the network, and use the .conflist extension. - -## Client Requirements - -`firecracker-task-driver` requires the following: - -- Linux 4.14+ Firecracker currently supports physical Linux x86_64 and aarch64 - hosts, running kernel version 4.14 or later. However, the aarch64 support is - not feature complete (alpha stage) - -- The [Firecracker binary][firecracker binary] - -- KVM enabled in your Linux kernel, and you have read/write access to /dev/kvm - -- tun kernel module - -- The firecracker-task-driver binary placed in the [plugin_dir][plugin_dir] - directory - -- ip6tables package - -- [Container network plugins][container network plugins] - -- [tc-redirect-tap][tc-redirect-tap] - -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[tc-redirect-tap]: https://github.com/awslabs/tc-redirect-tap -[container network plugins]: https://github.com/containernetworking/plugins -[firecracker binary]: https://github.com/firecracker-microvm/firecracker/releases -[firecracker-task-guide]: https://github.com/cneira/firecracker-task-driver -[allocation working directory]: /nomad/docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/content/plugins/drivers/community/iis.mdx b/website/content/plugins/drivers/community/iis.mdx deleted file mode 100644 index bdde310ebe3..00000000000 --- a/website/content/plugins/drivers/community/iis.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -layout: docs -page_title: Windows IIS task driver plugin -description: >- - Use the community-supported Windows IIS task driver (nomad-driver-iis) to run Windows IIS services in Nomad jobs. ---- - -# Windows IIS task driver plugin - -Name: `win_iis` - -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). - -For more detailed instructions on how to set up and use this driver, please -refer to the [project README.md][nomad-driver-iis]. - -## Task Configuration - -```hcl -task "iis-test" { - driver = "win_iis" - - config { - path = "C:\\inetpub\\wwwroot" - apppool_identity { - identity="SpecificUser" - username="vagrant" - password="vagrant" - } - } -} -``` - -The IIS task driver supports the following parameters: - -- `path` (string) - (Required) The path of the website directory. - -- `site_config_path` (string) - (Optional) The path should point to a valid IIS Site XML that is generated from an export. - -- `apppool_config_path` (string) - (Optional) The path should point to a valid IIS Application Pool XML that is generated from an export. - -- `apppool_identity` - (Optional) `ApplicationPoolIdentity` (default). The identity which the Application Pool will run under. - - - `identity` (string) - (Required) An identity is required to be set for Application Pools. Accepted inputs are `LocalService`, `LocalSystem`, `NetworkService`, `SpecificUser`, and `ApplicationPoolIdentity`. - - `username` (string) - (Optional) If `SpecificUser` was chosen, then provide the username. - - `password` (string) - (Optional) If `SpecificUser` was chosen, then provide the password. - -- `bindings` - (Optional) Bindings set here will be set for IIS. - - `hostname` (string) - (Optional) IIS hostname for a binding. - - `ipaddress` (string) - (Optional). `*` (default). IIS allows a binding to specify the IP Address being sent out. - - `resource_port` (string) - (Optional) Use a label from an established network block port. It is recommended to use this approach over using `port`. - - `port` (number) - (Optional) Specify a static port to use for the website. A port must be specified between `resource_port` or `port`. Ports set this way will not be recognized by nomad. - - `type` (string) - (Optional) Specifies which binding type IIS should use such as `http` or `https`. - - `cert_hash` (string) - (Optional) For SSL support, supply the cert hash here of a cert installed on the system. - -For optional parameters default value is assumed `nil`, if the default value is not specified in the documentation. - -## Networking - -Currently, `nomad-driver-iis` only supports host networking. No special configuration is needed as `nomad-driver-iis` -relies on IIS to manage the networking for Windows IIS website tasks. - -## Client Requirements - -`nomad-driver-iis` requires the following: - -- Windows 2016+ - -- Web Server enabled for IIS - -- The Nomad IIS driver binary ([build instructions][nomad-driver-iis]) - -## Plugin Options ((#plugin_options)) - -- `enabled` - The `IIS` driver may be disabled on hosts by setting this option to `false` (defaults to `true`). - -- `stats_interval` - This value defines how frequently you want to send `TaskStats` to nomad client. (defaults to `1 second`). - -An example of using these plugin options with the new [plugin -syntax][plugin] is shown below: - -```hcl -plugin "win_iis" { - client { - enabled = true - stats_interval = "30s" - } -} -``` - -Please note the plugin name should match whatever name you have specified for the external driver in the [plugin_dir][plugin_dir] directory. - -## Client Attributes - -The `IIS` driver will set the following client attributes: - -- `driver.win_iis.iis_version` - Sets to IIS version of IIS which is running on nomad client. - -[nomad-driver-iis]: https://github.com/Roblox/nomad-driver-iis -[plugin]: /nomad/docs/configuration/plugin -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[plugin-options]: #plugin_options diff --git a/website/content/plugins/drivers/community/index.mdx b/website/content/plugins/drivers/community/index.mdx index b564b258d6d..f64e0eb03e8 100644 --- a/website/content/plugins/drivers/community/index.mdx +++ b/website/content/plugins/drivers/community/index.mdx @@ -6,42 +6,14 @@ description: Learn about the community-supported task driver plugins that extend # Community task driver plugins -If you have authored a task driver plugin that you believe will be useful to the -broader Nomad community and you are committed to maintaining the plugin, please -file a PR to add your plugin to this page. +Task driver plugins authored and maintained by the Nomad community are listed on +the [Nomad integrations page](/nomad/integrations). On that page, select +**Community** from the **Tiers** list and **Task Drivers** from the **Types** +list to review Community-authored task driver plugins. -For details on authoring a task driver plugin, please refer to the [plugin -authoring guide][plugin_guide]. - -## Task Driver Plugins - -Nomad has a plugin system for defining task drivers. External task driver -plugins will have the same user experience as built in drivers. - -The following is a list of community-supported task drivers you can use with Nomad: - -- [containerd][nomad-driver-containerd] -- [Firecracker][firecracker-task-driver] -- [Jail task driver][jail-task-driver] -- [Lightrun][lightrun] -- [Pledge][pledge] -- [Pot][pot] -- [Rookout][rookout] -- [Singularity][singularity] -- [systemd-nspawn][nspawn-driver] -- [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 -[singularity]: /nomad/plugins/drivers/community/singularity -[jail-task-driver]: /nomad/plugins/drivers/community/jail-task-driver -[pot]: /nomad/plugins/drivers/community/pot -[firecracker-task-driver]: /nomad/plugins/drivers/community/firecracker-task-driver -[nspawn-driver]: /nomad/plugins/drivers/community/nspawn -[nomad-driver-iis]: /nomad/plugins/drivers/community/iis -[nomad-iis]: /nomad/plugins/drivers/community/nomad-iis -[nomad-driver-containerd]: /nomad/plugins/drivers/community/containerd -[lightrun]: /nomad/plugins/drivers/community/lightrun -[pledge]: /nomad/plugins/drivers/community/pledge +If you have authored a task driver plugin that you believe is useful to the +broader Nomad community and are committed to maintaining the plugin, +create a [Nomad GitHub issue](https://github.com/hashicorp/nomad/issues) so we can add your plugin to the Nomad Integrations page. +For details on authoring a task driver plugin, refer to the [plugin +authoring 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 deleted file mode 100644 index 84c9bcf368e..00000000000 --- a/website/content/plugins/drivers/community/jail-task-driver.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -layout: docs -page_title: Jail task driver plugin -description: >- - Use the community-supported Jail task driver to run application containers using FreeBSD jails in your Nomad jobs. ---- - -# Jail task driver plugin - -Name: `jail-task-driver` - -The Jail task driver provides an interface for using FreeBSD jails for running application -containers. You can download the external jail-task-driver [here][jail-task-driver]. For more detailed instructions on how to set up and use this driver, please refer to the [guide][jail-task-guide]. - -## Task Configuration - -```hcl -task "http-echo-jail" { - driver = "jail-task-driver" - config { - Path = "/zroot/iocage/jails/myjail/root" - Allow_raw_sockets = true - Allow_chflags = true - Ip4_addr = "em1|192.168.1.102" - Exec_start = "/usr/local/bin/http-echo -listen :9999 -text hello" - Rctl = { - Vmemoryuse = { - Action = "deny" - Amount = "1G" - Per = "process" - } - Openfiles = { - Action = "deny" - Amount = "500" - } - } - } - } -``` - -The Jail task driver supports most of [JAIL(8)][jail(8)] parameters, for a list of the currently supported parameters, please refer to the [Parameter Documentation][parameter-doc]. - -- `Path` - (Optional) The directory which is to be the root of the jail. - Defaults to the [allocation working directory]. - -- `Ip4` - (Optional) Control the availability of IPv4 addresses. Possible values are - **"inherit"** to allow unrestricted access to all system addresses, - **"new"** to restrict addresses via Ip4_addr, and "**disable"** to stop - the jail from using IPv4 entirely. - -~> Note : Setting the Ip4_addr parameter implies a value of **"new"** - -- `Ip4_addr` - (Optional) A list of IPv4 addresses assigned to the jail. If this is set, - the jail is restricted to using only these addresses. Any attempts to use other addresses fail, - and attempts to use wildcard addresses silently use the jailed address instead. For - IPv4 the first address given will be used as the source address when source address selection on - unbound sockets cannot find a better match. It is only possible to start multiple jails with - the same IP address if none of the jails has more than this - single overlapping IP address assigned to itself. - -- `Allow_raw_sockets` - (Optional) The jail root is allowed to create raw sockets. Setting - this parameter allows utilities like ping(8) and traceroute(8) to operate inside the jail. - If this is set, the source IP addresses are enforced to comply with the IP address bound to the jail, - regardless of whether or not the IP_HDRINCL flag has been set on the socket. - Since raw sockets can be used to configure and interact with various network subsystems, extra caution - should be used where privileged access to jails is given out to untrusted parties. - -## Resource Isolation - -Resource isolation on jails is enforced by [RCTL(8)][rctl-doc] all parameters for resource control -are supported. - -- `Rctl` - (Optional) Set resource limits on the jail, for a list of currently supported parameters, please refer to the [Parameter Documentation][parameter-doc]. - - * `Vmemoryuse` - (Optional) Address space limit,in bytes - * `Cputime` - (Optional) CPU time, in seconds - * `Datasize` - (Optional) data size, in bytes - * `Stacksize` - (Optional stack size, in bytes - * `Coredumpsize` - (Optional) core dump size, in bytes - * `Memoryuse` - (Optional) resident set size, in bytes - * `Memorylocked` - (Optional) locked memory, in bytes - * `Maxproc` - (Optional) number of processes - * `Openfiles` - (Optional) file descriptor table size - * `Vmemoryuse` - (Optional) address space limit,in bytes - * `Pseudoterminals` - (Optional) number of PTYs - * `Swapuse` - (Optional) swap space that may be reserved or used, in bytes - * `Nthr` - (Optional) number of threads - * `Msgqqueued` - (Optional) number of queued SysV messages - * `Msgqsize` - (Optional) SysV message queue size, in bytes - * `Nmsgq` - (Optional) number of SysV message queues - * `Nsem` - (Optional) number of SysV semaphores - * `Nsemop` - (Optional) number of SysV semaphores modified in a single semop(2) call - * `Nshm` - (Optional) number of SysV shared memory segments - * `Shmsize` - (Optional) SysV shared memory size, in bytes - * `Wallclock` - (Optional) wallclock time, in seconds - * `Pcpu` - (Optional) %CPU, in percents of a single CPU core - * `Readbps` - (Optional) filesystem reads, in bytes per second - * `Writebps` - (Optional) filesystem writes, in bytes per second - * `Readiops` - (Optional) filesystem reads, in operations per second - * `Writeiops` - (Optional) filesystem writes, in operations per second - -## Networking - -The job spec could specify the `Ip4addr` parameter to add the jail's ip address to an specific interface at jail -startup or the `Vnet` parameter to create a virtual network stack. Please refer to [JAIL(8)][jail(8)] for more details. - -- `vnet jail` - Example taken from Lucas, Michael W. FreeBSD Mastery: Jails (IT Mastery Book 15). - -```hcl - task "test01" { - driver = "jail-task-driver" - config { - Path = "/zroot/iocage/jails/myjail/root" - Host_hostname = "nomad00" - Exec_clean = true - Exec_start = "sh /etc/rc" - Exec_stop = "sh /etc/rc.shutdown" - Mount_devfs = true - Exec_prestart = "logger trying to start " - Exec_poststart = "logger jail has started" - Exec_prestop = "logger shutting down jail " - Exec_poststop = "logger has shut down jail " - Exec_consolelog ="/var/tmp/vnet-example" - Vnet = true - Vnet_nic = "e0b_loghost" - Exec_prestart = "/usr/share/examples/jails/jib addm loghost em1" - Exec_poststop = "/usr/share/examples/jails/jib destroy loghost " - } - } -``` - -## Client Requirements - -`jail-task-driver` requires the following: - -- 64-bit FreeBSD 12.0-RELEASE host -- The FreeBSD's Nomad binary -- The jail-task-driver binary placed in the [plugin_dir][plugin_dir] directory. -- If resource control is going be used then [RACCT][racct-doc] must be enabled - -[jail-task-driver]: https://github.com/cneira/jail-task-driver/releases -[jail-task-guide]: https://github.com/cneira/jail-task-driver#installation -[jail(8)]: https://www.freebsd.org/cgi/man.cgi?jail(8) -[racct-doc]: https://www.freebsd.org/doc/handbook/security-resourcelimits.html -[rctl-doc]: https://www.freebsd.org/doc/handbook/security-resourcelimits.html -[parameter-doc]: https://github.com/cneira/jail-task-driver/blob/master/Parameters.md -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[allocation working directory]: /nomad/docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/content/plugins/drivers/community/lightrun.mdx b/website/content/plugins/drivers/community/lightrun.mdx deleted file mode 100644 index 13ed6162bbb..00000000000 --- a/website/content/plugins/drivers/community/lightrun.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -layout: docs -page_title: Lightrun task driver plugin -description: Use the community-supported Lightrun task driver to run your Java application with Lightrun in your Nomad jobs. ---- - -# Lightrun task driver plugin - -Name: `lightrun-java` - -The Lightrun Nomad driver is used to execute Java applications packaged into a -Java Jar file and automatically add the Lightrun agent to them. - -[Lightrun][lightrun_website] is a developer-native observability platform. With -Lightrun you can add logs, snapshots (virtual breakpoints), and metrics to -production applications without the need for redeployments or restarts. You can -use Lightrun directly from your IDE or CLI to observe, understand and debug -your application at runtime. - -Refer to the [Lightrun documentation][lightrun_docs] for more information about -Lightrun. - -## Prerequisites - -1. Download or clone the [Lightrun driver repository][repo]. -1. Find the `lightrun-java-driver` driver in the repository's root folder. -1. Copy the driver to your Nomad plugins directory (or create one if it doesn't - exist). -1. Grant executable permissions to the driver file: - - ```shell-session - $ chmod +x ./plugins/lightrun-java-driver - ``` - -1. When running the Nomad agent, make sure to specify the path to your plugins - directory: - - ```shell-session - $ sudo nomad agent -dev -bind 0.0.0.0 -log-level DEBUG -plugin-dir= - ``` - -## Task Configuration - -```hcl -task "run-with-lightrun" { - driver = "lightrun-java" - - config { - lightrun_server = "https://app.lightrun.com/company/" - lightrun_secret = "" - lightrun_certificate = "ee80811b38e7e6c2dc4cc372cbea86bd86b446b012e427f2e19bf094afba5d12" - } -} -``` - -The `lightrun-java` driver accepts all configuration options of the Nomad -[`java`] driver. - -Additionally, the `lightrun-java` driver requires the following configuration in -the job spec. To find these configurations, log into the -[Lightrun Management Portal][lightrun_portal] and refer to the **Download the -Agent** section: - -- `lightrun_server` - The Lightrun server you are working against, including - your company name. - -- `lightrun_secret` - Lightrun secret is used for authorization against the - Lightrun server. - -- `lightrun_certificate` - Used for certificate pinning. - -A full job file example can be found in the repo at [`example/example.driver.nomad`][example-config]. - -[lightrun_docs]: https://docs.lightrun.com -[lightrun_website]: https://www.lightrun.com -[lightrun_portal]: https://app.lightrun.com -[repo]: https://github.com/lightrun-platform/lightrun-n-nomad -[example-config]: https://github.com/lightrun-platform/lightrun-n-nomad/blob/main/example/example.driver.nomad -[`java`]: /nomad/docs/drivers/java diff --git a/website/content/plugins/drivers/community/nomad-iis.mdx b/website/content/plugins/drivers/community/nomad-iis.mdx deleted file mode 100644 index af9cb179aca..00000000000 --- a/website/content/plugins/drivers/community/nomad-iis.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -layout: docs -page_title: Nomad IIS task driver plugin -description: >- - Use the community-supported Nomad IIS driver to run Windows IIS services in Nomad jobs. ---- - -# Nomad IIS task driver plugin - -Name: `nomad_iis` - -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. - - -At the moment I'm developing this plugin as a hobby project. Version 1 has not yet been reached and breaking changes may still occur. - - -## Sample Job - -```hcl -job "iis-test" { - datacenters = ["dc1"] - type = "service" - - group "iis-test" { - count = 1 - - network { - port "httplabel" {} - } - - task "iis-test" { - driver = "iis" - - config { - application { - path = "C:\\inetpub\\wwwroot" - } - application { - alias = "subapp" - path = "C:\\inetpub\\wwwroot" - } - - binding { - type = "http" - port = "httplabel" - } - } - - env { - my_key = "my-value" - } - - resources { - cpu = 100 - memory = 20 - } - } - } -} -``` - -Please refer to the project's [Readme](https://github.com/sevensolutions/nomad-iis/blob/main/README.md) for the full documentation and configuration options. - -## Download - -Download the latest version from [here](https://github.com/sevensolutions/nomad-iis/releases). - -## Source Code - -You can get the full source code of this plugin on [Github](https://github.com/sevensolutions/nomad-iis). diff --git a/website/content/plugins/drivers/community/nspawn.mdx b/website/content/plugins/drivers/community/nspawn.mdx deleted file mode 100644 index 057205b329f..00000000000 --- a/website/content/plugins/drivers/community/nspawn.mdx +++ /dev/null @@ -1,204 +0,0 @@ ---- -layout: docs -page_title: Task driver plugin for nspawn -description: Use the community-supported nspawn task driver to run application containers using systemd-nspawn in Nomad jobs. ---- - -# nspawn Task Driver Plugin - -Name: `nspawn` - -The `nspawn` driver provides an interface for using systemd-nspawn for running -application containers. You can download the external nspawn driver from the -[nomad-driver-nspawn releases page][nspawn-driver]. For more detailed instructions on how to set up and use -this driver, please refer to the [examples in the nomad-driver-nspawn repository][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/tree/master/example -[plugin]: /nomad/docs/configuration/plugin -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[plugin-options]: #plugin-options -[client_options]: /nomad/docs/configuration/client#options -[docker_driver]: /nomad/docs/drivers/docker#using-the-port-map -[consul_connect_integration]: /nomad/docs/integrations/consul-connect diff --git a/website/content/plugins/drivers/community/pledge.mdx b/website/content/plugins/drivers/community/pledge.mdx deleted file mode 100644 index 4b010f564b3..00000000000 --- a/website/content/plugins/drivers/community/pledge.mdx +++ /dev/null @@ -1,332 +0,0 @@ ---- -layout: docs -page_title: Pledge task driver plugin -description: Use the community-supported Pledge task driver to block unwanted syscall and filesystem access in Nomad jobs. ---- - -# Pledge task driver plugin - -Name: `pledge` - -The `pledge` driver executes programs similar to `exec` or `raw_exec`, but -provides sandboxing by restricting syscalls the process is allowed to make. -The `pledge` driver uses the [Landlock LSM][landlock] to restrict filesystem -access, which can be significantly more efficient than creating a `chroot`. -Isolation of CPU and memory resources is provided by leveraging features of -cgroups v2. Network, PID, and IPC isolation is powered by Linux namespaces. - -Source on [GitHub][repository] - -Downloads on GitHub [releases][releases] - -#### Use cases - -The `pledge` driver is intended as a replacement for `raw_exec`. Sometimes -there are those management tasks that just need to be run as `root` and directly -access the filesystem or perform privileged operations. While `raw_exec` -provides no isolation, the `pledge` driver uses Landlock to restrict the files -or directories the task is allowed to access and modify. Specific groups of -system calls are allow-listed in the task configuration, greatly reducing the -attack surface of a mis-configured or compromised task. - -#### About - -The `pledge` driver is fundamentally powered by the [pledge utility for Linux] -[pledge] by Justine Tunney. The driver invokes this `pledge.com` CLI tool along -with `nsenter` and `unshare` to create a strict sandbox in which to execute a -given command. - -## Task Configuration - -```hcl -task "http" { - driver = "pledge" - config { - command = "python3" - args = ["-m", "http.server", "${NOMAD_PORT_http}", "--directory", "${NOMAD_TASK_DIR}"] - promises = "stdio rpath inet" - unveil = ["r:/etc/mime.types", "r:${NOMAD_TASK_DIR}"] - } -} -``` - -The `pledge` driver supports the following task configuration in the job spec: - -- `command` - The command to execute. Must be provided. The driver will search - for the command on the `$PATH` of the Nomad Client unless an absolute path - is given. - -- `args` - (Optional) A list of arguments to the `command`. References to - environment variables or any interpolable Nomad variables will be interpolated - before launching the task. - -- `promises` - A set of promises needed for the command to run. See below for - more information. - -- `unveil` - (Optional) A list of filepaths and access rights to grant to the - command. See below for more information. - -- `importance` - (Optional) One of `"lowest"`, `"low"`, `"normal"`, `"high"`, - `"highest"`. Indicates the `nice` value with which to run `command` (default - is `"normal"`). A lower importance indicates the command should be given a - lower priority with regard to CPU time relative to other tasks. - -## Syscall Isolation (promises) - -When using the `pledge` task driver, by default most syscalls will become -unavailable. A process that attempts to use an unavailable syscall will receive -an `EPERM` error from the kernel. By specifying a set of `promises`, additional -syscalls will be made available to the `command`. - -See the complete documetation for [promises][promises]. - -| Promise | Description | -| ------- | ------------| -| `stdio` | allow stdio, threads, and benign system calls | -| `rpath` | allow filesystem read operations | -| `wpath` | allow filesystem write operations | -| `cpath` | allow filesystem create operations | -| `dpath` | allow creation of special files | -| `flock` | allow file locking | -| `tty` | allow terminal ioctls | -| `recvfd` | allow recvmsg | -| `sendfd` | allow sendmsg | -| `fattr` | allow changing some struct stat bits | -| `inet` | allow IPv4 and IPv6 | -| `unix` | allow using Unix Domain Sockets | -| `dns` | allow DNS | -| `proc` | allow fork process creation and control | -| `id` | allow setuid and friends | -| `exec` | allow executing binaries | -| `prot_exec` | allow creating executable memory | -| `vminfo` | allow operations around reading `/proc` | -| `tmppath` | allow access to `/tmp` | - -## Filesystem Isolation (unveil) - -By default the `command` will not be able to access the filesystem. Using some -promises will implicitly allow access to specific parts of the filesystem where -applicable. The `unveil` configuration is used to grant access to additional -filesytem paths at a specified permission level. - -The format of the `unveil` parameter is a list of paths and associated -permissions. Permissions can be any combination of `r`, `w`, `c` and `x` for -read, write, create and execute privileges. - -Note that reading a file also requires the `rpath` promise, writing a file -requires the `wpath` promise, creating a file requires the `cpath` promise, and -executing a program requires the `exec` promise. - -#### Examples - -This example allows reading of the `/srv/www` directory. - -```hcl -unveil = ["r:/srv/www"] -``` - -This example allows executing `/opt/bin/program` and reading `/etc/prog.d`. - -```hcl -unveil = ["x:/opt/bin/program", "r:/etc/prog.d"] -``` - -It can be useful to `unveil` the Nomad Task Directory, which can be done by -specifying the interpolation value. - -```hcl -unveil = ["rwc:${NOMAD_TASK_DIR}"] -``` - -## Networking - -The `pledge` driver supports `none`, `host`, and `group` networking modes. - -#### host networking - -If using `host` networking mode, it can be very convenient to bless the -[pledge][pledge] utility with the `cap_net_bind_service` Linux capability. This will -enable Nomad tasks using the pledge driver to bind to privileged ports (i.e. -below 1024) while using host networking mode. - -```shell-session -sudo setcap cap_net_bind_service+eip /opt/bin/pledge-1.8.com -``` - -For convenience the `driver.pledge.cap.net_bind` Client attribute will indicate -whether the Linux capability is set on the executable. - -#### bridge networking - -If using `bridge` networking mode, be sure to install the standard [CNI plugins] -[cni] as required by the Nomad client. - -## Client Requirements - -The `pledge` driver requires the following: - -- 64-bit amd64 Linux host - - kernel version 5.13+ - - cgroups v2 enabled -- The `pledge` driver binary placed in [plugin_dir][plugin_dir] -- The `pledge.com` utility executable on the host - -## Plugin Options - -- `pledge_executable` - The path to the `pledge.com` binary. The pledge utility -can be [downloaded][download] directly from its creator, or compiled manually -from [source][pledge_github]. - -```hcl -plugin "nomad-pledge-driver" { - config { - pledge_executable = "/opt/bin/pledge-1.8.com" - } -} -``` - -## Client Attributes - -The `pledge` driver will set the following Client attributes: - -| Attribute | Description | -| ----------| ----------- | -| `driver.pledge` | set to `1` if the driver is enabled | -| `driver.pledge.abs` | the absolute path to the pledge.com utility | -| `driver.pledge.cap.net_bind` | indicates whether the NET_BIND linux capability is set | -| `driver.pledge.os` | the detected operating system | - -## Resource Isolation - -CPU and memory resource isolation is enforced by cgroups v2 features, and is -configured through the resources block in task configuration. - -```hcl -resources { - cores = 3 - memory = 512 -} -``` - -#### cpu bandwidth - -The `pledge` driver always enforces a maximum CPU bandwidth available to the -task. The bandwidth is calculated whether `resources.cpu` or `resources.cores` -is configured. - -If `resources.cores` is set, the scheduler reserves that many CPU cores for use -by the task, and only this task will be able to run on those cores. - -#### memory oversubscription - -If the Nomad scheduler is configured to enable memory [oversubscription] -[oversub], the `pledge` driver will enable configuring `memory_max` in addition -to `memory`. In this case, `memory_max` indicates the maximum amount of memory -the task is able to request before being OOM killed, and `memory` represents a -minimum amount of memory the kernel will guarantee is available for the Task. - -```hcl -resources { - cpu = 2000 - memory = 1024 - memory_max = 2048 -} -``` - -## Capabilities - -The `pledge` driver implements the following [capabilities][capabilities]. - -| Feature | Implementation | -| ------------ | ------------------| -| send signals | true | -| exec | false | -| filesystem isolation | none (landlock) | -| network isolation | host, group, none | -| volume mounting | false | - -For sending signals, use the `nomad alloc signal` command. - -## Examples - -A larger set of examples are available in the [source][hack] repository. - -Showing how to `curl example.com`. - -```hcl -job "curl" { - type = "batch" - group "group" { - task "curl" { - driver = "pledge" - user = "nobody" - config { - command = "curl" - args = ["example.com"] - promises = "stdio rpath inet dns sendfd" - } - } - } -} -``` - -An example using the Python built-in HTTP server to render a trivial web page. - -```hcl -job "http" { - group "group" { - network { - mode = "host" - port "http" { static = 8181 } - } - - task "task" { - driver = "pledge" - user = "nobody" - config { - command = "python3" - args = ["-m", "http.server", "${NOMAD_PORT_http}", "--directory", "${NOMAD_TASK_DIR}"] - promises = "stdio rpath inet" - unveil = ["r:/etc/mime.types", "r:${NOMAD_TASK_DIR}"] - } - - template { - destination = "local/index.html" - data = < - - example -

Hello, friend!

- -EOH - } - } - } -} -``` - -## Troubleshooting - -When setting up a new Task using the `nomad-pledge-driver` task driver, it -helps to run the command manually using the `pledge` utility to make sure the -necessary promises and unveil paths are well understood. To figure out which -syscalls process needs to make, it can be run under `strace -ff`. When a syscall -is blocked, you'll see `"EPERM (Operation not permitted)"` - -```shell-session -strace -ff /opt/bin/pledge-1.8.com -p "stdio rpath inet" -- curl example.com -``` - -[capabilities]: /nomad/docs/concepts/plugins/task-drivers#capabilities-capabilities-error -[cni]: https://developer.hashicorp.com/nomad/docs/install -[download]: https://justine.lol/pledge/#download -[hack]: https://github.com/shoenig/nomad-pledge-driver/tree/main/hack -[landlock]: https://docs.kernel.org/security/landlock.html -[oversub]: https://developer.hashicorp.com/nomad/api-docs/operator/scheduler#memoryoversubscriptionenabled-1 -[pledge]: https://justine.lol/pledge/ -[pledge_github]: https://github.com/jart/pledge -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[promises]: https://justine.lol/pledge/#promises -[repository]: https://github.com/shoenig/nomad-pledge-driver -[releases]: https://github.com/shoenig/nomad-pledge-driver/releases - diff --git a/website/content/plugins/drivers/community/pot.mdx b/website/content/plugins/drivers/community/pot.mdx deleted file mode 100644 index d1aae2ef7d7..00000000000 --- a/website/content/plugins/drivers/community/pot.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -layout: docs -page_title: Pot task driver plugin -description: >- - Use the community-supported Pot task driver to run pot containers inside a FreeBSD Jail in Nomad jobs. ---- - -# Pot task driver plugin - -Name: `pot` - -The Pot task driver provides an interface for using [pot][pot-github-repo] for dynamically running applications inside a FreeBSD Jail. -Download the external nomad-pot-driver from its [releases page][nomad-pot-driver]. - -## Task Configuration - -```hcl -task "nginx-pot" { - driver = "pot" - - config { - image = "https://pot-registry.zapto.org/registry/" - pot = "FBSD120-nginx" - tag = "1.0" - command = "nginx" - args = [ - "-g 'daemon off;'" - ] - network_mode = "public-bridge" - port_map = { - http = "80" - } - copy = [ - "/root/index.html:/usr/local/www/nginx-dist/index.html", - "/root/nginx.conf:/usr/local/etc/nginx/nginx.conf" - ] - mount = [ - "/tmp/test:/root/test", - ] - mount_read_only = [ - "/tmp/test2:/root/test2" - ] - extra_hosts = [ - "artifactory.yourdomain.com:192.168.0.1", - "mail.yourdomain.com:192.168.0.2" - ] - } -} -``` - -The pot task driver supports the following parameters: - -- `image` - The url for the http registry from where to get the image. - -- `pot` - Name of the image in the registry. - -- `tag` - Version of the image. - -- `command` - Command that is going to be executed once the jail is started. - -- `args` - (Optional) List of options for the command executed on the command argument. - -- `network_mode` - (Optional) Defines the network mode of the pot. Default: **"public-bridge"** - - Possible values are: - - **"public-bridge"** pot creates an internal virtual network with a NAT table where all traffic is going to be sent. - - **"host"** pot bounds the jail directly to a host port. - -- `port_map` - (Optional) Sets the port on which the application is listening inside of the jail. If not set, the application will inherit the port configuration from the image. - -- `copy` - (Optional) Copies a file from the host machine to the pot jail in the given directory. - -- `mount` - (Optional) Mounts a read/write folder from the host machine to the pot jail. - -- `mount_read_only` - (Optional) Mounts a read only directory inside the pot jail. - -- `extra_hosts` - (Optional) A list of hosts, given as host:IP, to be added to /etc/hosts - -## Client Requirements - -`pot Task Driver` requires the following: - -- 64-bit FreeBSD 12.0-RELEASE host . -- The FreeBSD's Nomad binary (available as a package). -- The pot-task-driver binary placed in the [plugin_dir][plugin_dir] directory. -- Installing [pot][pot-github-repo] and following the install [guide][pot-install-guide]. -- Webserver from where to serve the images. (simple file server) -- Following lines need to be included in your rc.conf - -``` -nomad_user="root" -nomad_env="PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/sbin:/bin" -``` - -[nomad-pot-driver]: https://github.com/trivago/nomad-pot-driver -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[pot-github-repo]: https://github.com/pizzamig/pot -[pot-install-guide]: https://github.com/pizzamig/pot/blob/master/share/doc/pot/Installation.md diff --git a/website/content/plugins/drivers/community/rookout.mdx b/website/content/plugins/drivers/community/rookout.mdx deleted file mode 100644 index 8451cc37712..00000000000 --- a/website/content/plugins/drivers/community/rookout.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: docs -page_title: Rookout task driver plugin -description: Use the community-supported Rookout task driver to run your Java application with Rookout in Nomad jobs. ---- - -# Rookout task driver plugin - -Name: `java-rookout` - -The Rookout Nomad driver is used to execute Java applications packaged into a Java Jar file and automatically add the Rookout SDK to them. - -[Rookout](https://rookout.com) is a developer solution for Cloud Native debugging and live-data collection. Rookout’s Non-Breaking Breakpoints let you collect any type of data on the fly with no extra coding, redeployments, or restarts. - -More info about the Rookout SDK is available in the [Rookout docs](https://docs.rookout.com). - -## Prerequisites - -Using this driver requires you to have a Rookout token which you can get by [signing up](http://rookout.com). - -This driver is based on the Nomad [Java driver](/nomad/docs/drivers/java). - -1. Clone the driver's repo: `git clone https://github.com/rookout/rookout-nomad-driver` -2. Change to the cloned dir: `cd rookout-nomad-driver` -3. Create a plugin dir (unless you already have one for your Nomad installation): `mkdir plugins` -4. Copy the corresponding binary from the `bin` folder, for example: `cp ./bin/java-rookout-linux-x64 plugins/java-rookout` -5. Make sure that the driver has execution permission: `chmod +x ./plugins/java-rookout` -6. When running the Nomad agent, be sure to set the plugins dir accordingly, for example: `sudo nomad agent -dev -plugin-dir=/home/user/rookout-nomad-driver/plugins` - -## Task Configuration - -The `java-rookout` driver accepts all configuration options of the [`java`](/nomad/docs/drivers/java) driver. - -Set the `rookout_token` config key to your Rookout token, or define it as a variable and pass it as a parameter. - -For example: -```hcl -task "run-with-rookout" { - driver = "java-rookout" - - config { - rookout_token = "ea15c38c4e05cf4549b..." - } -} -``` - -Additional Rookout configuration can be passed as environment variables like so: -```hcl -env { - ROOKOUT_REMOTE_ORIGIN="https://github.com/Rookout/tutorial-java" -} -``` diff --git a/website/content/plugins/drivers/community/singularity.mdx b/website/content/plugins/drivers/community/singularity.mdx deleted file mode 100644 index bd6e6167e26..00000000000 --- a/website/content/plugins/drivers/community/singularity.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -layout: docs -page_title: Singularity task driver plugin -description: >- - Use the community-supported Singularity task driver to run application containers using Singularity in Nomad jobs. ---- - -# Singularity task driver plugin - -Name: `Singularity` - -The `Singularity` driver provides an interface for using Singularity for running application -containers. Download the external Singularity driver from its [releases page][singularity-driver]. - -## Task Configuration - -```hcl -task "lolcow" { - driver = "Singularity" - - config { - # this example run an image from sylabs container library with the - # canonical example of lolcow - image = "library://sylabsed/examples/lolcow:latest" - # command can be run, exec or test - command = "run" - } -} -``` - -The `Singularity` driver supports the following configuration in the job spec: - -- `image` - The Singularity image to run. It can be a local path or a supported URI. - - ```hcl - config { - image = "library://sylabsed/examples/lolcow:latest" - } - ``` - -- `verbose` - (Optional) Enables extra verbosity in the Singularity runtime logging. - Defaults to `false`. - - ```hcl - config { - verbose = "false" - } - ``` - -- `debug` - (Optional) Enables extra debug output in the Singularity runtime - logging. Defaults to `false`. - - ```hcl - config { - debug = "false" - } - ``` - -- `command` - Singularity command action; can be `run`, `exec` or `test`. - - ```hcl - config { - command = "run" - } - ``` - -- `args` - (Optional) Singularity command action arguments, when trying to pass arguments to `run`, `exec` or `test`. - Multiple args can be given by a comma separated list. - - ```hcl - config { - args = [ "echo", "hello Cloud" ] - } - ``` - -- [`binds`][bind] - (Optional) A user-bind path specification. This spec has the format `src[:dest[:opts]]`, where src and - dest are outside and inside paths. If dest is not given, it is set equal to src. - Mount options ('opts') may be specified as 'ro' (read-only) or 'rw' (read/write, which - is the default). Multiple bind paths can be given by a comma separated list. - - ```hcl - config { - bind = [ "host/path:/container/path" ] - } - ``` - -- [`overlay`][overlay] - (Optional) Singularity command action flag, to enable an overlayFS image for persistent data - storage or as read-only layer of container. Multiple overlay paths can be given by a comma separated list. - - ```hcl - config { - overlay = [ "host/path/to/overlay" ] - } - ``` - -- [`security`][security] - (Optional) Allows the root user to leverage security modules such as - SELinux, AppArmor, and seccomp within your Singularity container. - You can also change the UID and GID of the user within the container at runtime. - - ```hcl - config { - security = [ "uid:1000 " ] - } - ``` - -- `contain` - (Optional) Use minimal `/dev` and empty other directories (e.g. `/tmp` and `$HOME`) instead of sharing filesystems from your host. - - ```hcl - config { - contain = "false" - } - ``` - -- `workdir` - (Optional) Working directory to be used for `/tmp`, `/var/tmp` and `$HOME` (if -c/--contain was also used). - - ```hcl - config { - workdir = "/path/to/folder" - } - ``` - -- `pwd` - (Optional) Initial working directory for payload process inside the container. - - ```hcl - config { - pwd = "/path/to/folder" - } - ``` - -## Networking - -Currently the `Singularity` driver only supports host networking. For more detailed instructions on how to set up networking options, please refer to the `Singularity` user guides [singularity-network] - -## Client Requirements - -The `Singularity` driver requires the following: - -- 64-bit Linux host -- The `linux_amd64` Nomad binary -- The Singularity driver binary placed in the [plugin_dir][plugin_dir] directory. -- [`Singularity`][singularity] v3.1.1+ to be installed - -## Plugin Options ((#plugin_options)) - -- `enabled` - The `Singularity` driver may be disabled on hosts by setting this option to `false` (defaults to `true`). - -- `singularity_cache` - The location in which all containers are stored (commonly defaults to `/var/lib/singularity`). See [`Singularity-cache`][singularity-cache] for more details. - -An example of using these plugin options with the new [plugin -syntax][plugin] is shown below: - -```hcl -plugin "nomad-driver-Singularity" { - config { - enabled = true - singularity_path = "/var/lib/singularity" - } -} -``` - -Please note the plugin name should match whatever name you have specified for the external driver in the [plugin_dir][plugin_dir] directory. - -## Client Attributes - -The `Singularity` driver will set the following client attributes: - -- `driver.singularity` - Set to `1` if Singularity is found and enabled on the host node. -- `driver.singularity.version` - Version of `Singularity` e.g.: `3.1.0`. - -## Resource Isolation - -This driver supports CPU and memory isolation via the `Singularity` cgroups feature. Network -isolation is supported via `--net` and `--network` feature (Singularity v3.1.1+ required). - -[singularity-driver]: https://github.com/sylabs/nomad-driver-singularity -[singularity_man]: https://linuxcontainers.org/Singularity/manpages/man5/Singularity.container.conf.5.html#lbAM -[plugin]: /nomad/docs/configuration/plugin -[plugin_dir]: /nomad/docs/configuration#plugin_dir -[plugin-options]: #plugin_options -[singularity]: https://github.com/sylabs/singularity -[singularity-cache]: https://www.sylabs.io/guides/3.1/user-guide/appendix.html#c -[bind]: https://www.sylabs.io/guides/3.1/user-guide/bind_paths_and_mounts.html -[security]: https://www.sylabs.io/guides/3.1/user-guide/security_options.html -[overlay]: https://www.sylabs.io/guides/3.1/user-guide/persistent_overlays.html -[singularity-network]: https://www.sylabs.io/guides/3.1/user-guide/networking.html diff --git a/website/data/plugins-nav-data.json b/website/data/plugins-nav-data.json index f03f8d7283f..bcfa81bf67c 100644 --- a/website/data/plugins-nav-data.json +++ b/website/data/plugins-nav-data.json @@ -45,47 +45,47 @@ }, { "title": "containerd", - "path": "drivers/community/containerd" + "href": "https://github.com/Roblox/nomad-driver-containerd" }, { "title": "Pledge", - "path": "drivers/community/pledge" + "href": "https://github.com/shoenig/nomad-pledge-driver" }, { "title": "Firecracker driver", - "path": "drivers/community/firecracker-task-driver" + "href": "https://github.com/cneira/firecracker-task-driver" }, { "title": "Jail task driver", - "path": "drivers/community/jail-task-driver" + "href": "https://github.com/cneira/jail-task-driver" }, { "title": "Lightrun", - "path": "drivers/community/lightrun" + "href": "https://docs.lightrun.com/integrations/nomad/" }, { "title": "Pot", - "path": "drivers/community/pot" + "href": "https://github.com/bsdpot/nomad-pot-driver" }, { "title": "Rookout", - "path": "drivers/community/rookout" + "href": "https://github.com/Rookout/rookout-nomad-driver" }, { "title": "Singularity", - "path": "drivers/community/singularity" + "href": "https://github.com/hpcng/nomad-driver-singularity" }, { "title": "systemd-nspawn", - "path": "drivers/community/nspawn" + "href": "https://github.com/JanMa/nomad-driver-nspawn" }, { - "title": "Windows IIS", - "path": "drivers/community/iis" + "title": "Windows IIS - Roblox", + "href": "https://github.com/Roblox/nomad-driver-iis" }, { "title": "Windows IIS", - "path": "drivers/community/nomad-iis" + "href": "https://nomad-iis.sevensolutions.cc/" } ] } diff --git a/website/redirects.js b/website/redirects.js index c83f9f83279..dddc1f52786 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -129,4 +129,59 @@ module.exports = [ destination: '/nomad/plugins/devices/usb', permanent: true, }, + { + source: '/nomad/drivers/community/containerd', + destination: 'https://github.com/Roblox/nomad-driver-containerd', + permanent: true, + }, + { + source: '/nomad/drivers/community/pledge', + destination: 'https://github.com/shoenig/nomad-pledge-driver', + permanent: true, + }, + { + source: '/nomad/drivers/community/firecreacker-task-driver', + destination: 'https://github.com/cneira/firecracker-task-driver', + permanent: true, + }, + { + source: '/nomad/drivers/community/jail-task-driver', + destination: 'https://github.com/cneira/jail-task-driver', + permanent: true, + }, + { + source: '/nomad/drivers/community/lightrun', + destination: 'https://docs.lightrun.com/integrations/nomad/', + permanent: true, + }, + { + source: '/nomad/drivers/community/pot', + destination: 'https://github.com/bsdpot/nomad-pot-driver', + permanent: true, + }, + { + source: '/nomad/drivers/community/rookout', + destination: 'https://github.com/Rookout/rookout-nomad-driver', + permanent: true, + }, + { + source: '/nomad/drivers/community/singularity', + destination: 'https://github.com/hpcng/nomad-driver-singularity', + permanent: true, + }, + { + source: '/nomad/drivers/community/nspawn', + destination: 'https://github.com/JanMa/nomad-driver-nspawn', + permanent: true, + }, + { + source: '/nomad/drivers/community/iis', + destination: 'https://github.com/Roblox/nomad-driver-iis', + permanent: true, + }, + { + source: '/nomad/drivers/community/nomad-iis', + destination: 'https://nomad-iis.sevensolutions.cc/', + permanent: true, + }, ] From 8cd186ede597531aa191642c5fa3eda35571adcd Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Mon, 19 May 2025 14:10:18 -0500 Subject: [PATCH 2/2] fix typo in redirect.js --- website/redirects.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/redirects.js b/website/redirects.js index dddc1f52786..7cad371967f 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -140,7 +140,7 @@ module.exports = [ permanent: true, }, { - source: '/nomad/drivers/community/firecreacker-task-driver', + source: '/nomad/drivers/community/firecracker-task-driver', destination: 'https://github.com/cneira/firecracker-task-driver', permanent: true, },