docs: add plugin docs for pledge task driver #17823
Conversation
shoenig
changed the title
shoenig
force-pushed
the
docs-pledge-driver
branch
from
6056336
to
5947c51
Compare
shoenig
force-pushed
the
docs-pledge-driver
branch
from
5947c51
to
9468656
Compare
Add pledge driver to the set of Community drivers.
shoenig
force-pushed
the
docs-pledge-driver
branch
from
9468656
to
8c7573c
Compare
There was a problem hiding this comment.
LGTM once the minor items are cleaned up.
Preview link: https://nomad-o1pyfiqi9-hashicorp.vercel.app/nomad/plugins/drivers/community/pledge
| @@ -44,3 +45,5 @@ Below is a list of community-supported task drivers you can use with Nomad: | |||
| [nomad-driver-iis]: /nomad/plugins/drivers/community/iis | |||
| [nomad-driver-containerd]: /nomad/plugins/drivers/community/containerd | |||
| [lightrun]: /nomad/plugins/drivers/community/lightrun | |||
| [pledge]: /nomad/plugins/drviers/community/pledge | |||
There was a problem hiding this comment.
| [pledge]: /nomad/plugins/drviers/community/pledge | |
| [pledge]: /nomad/plugins/drivers/community/pledge |
| 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) |
There was a problem hiding this comment.
| [capabilities]: /nomad/docs/concepts/plugins/task-drivers#capabilities-capabilities-error) | |
| [capabilities]: /nomad/docs/concepts/plugins/task-drivers#capabilities-capabilities-error |
|
|
||
| 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 an attuned sandbox in which to execute a |
There was a problem hiding this comment.
Is this supposed to be "attenuated"?
There was a problem hiding this comment.
Heh no, I was using attuned like "define the sandbox in harmony with the command being run". But that's obviously not that clear, so I'll change the wording.
|
|
||
| If using `host` networking mode, it can be very convenient to bless the | ||
| pledge.com utility with the `cap_net_bind_service` Linux capability. This will | ||
| enable Nomad tasks using the pledge driver to bind to privilged ports (i.e. |
There was a problem hiding this comment.
| enable Nomad tasks using the pledge driver to bind to privilged ports (i.e. | |
| enable Nomad tasks using the pledge driver to bind to privileged ports (i.e. |
| If the Nomad scheduler is configured to enable memory [oversubscription] | ||
| [oversub], the `pledge` driver will correctly enable configuring `memory_max` | ||
| in addition to `memory`. In this case, `memory_max` indicates the maximum amount |
There was a problem hiding this comment.
This seems a little wordy? Maybe cut down a bit to:
| If the Nomad scheduler is configured to enable memory [oversubscription] | |
| [oversub], the `pledge` driver will correctly enable configuring `memory_max` | |
| in addition to `memory`. In this case, `memory_max` indicates the maximum amount | |
| If the Nomad scheduler is configured to enable memory [oversubscription] | |
| [oversub], the `pledge` driver will allow configuring `memory_max` | |
| in addition to `memory`. In this case, `memory_max` indicates the maximum amount |
| [oversub], the `pledge` driver will correctly 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 gauruntee is available for |
There was a problem hiding this comment.
| represents a minimum amount of memory the kernel will gauruntee is available for | |
| represents a minimum amount of memory the kernel will guarantee is available for |
| ## Troubleshooting | ||
|
|
||
| When setting up a new Task using the `pledge` task driver, it helps to run | ||
| the command manually using the `pledge.com` utility to make sure the necessary |
There was a problem hiding this comment.
The text is inconsistent on whether it uses "pledge.com" or "pledge.com". Maybe we should use the backticks everywhere? (This also prevents folks from thinking it's a domain name.)
There was a problem hiding this comment.
The tool itself is actually being renamed to pledge
but hasn't been released yet with that name
| | ------------ | ------------------| | ||
| | send signals | true | | ||
| | exec | false | | ||
| | filesystem isolation | Landlock LSM | |
There was a problem hiding this comment.
Did we end up settling on whether we were going to have a separate isolation capability for this?
There was a problem hiding this comment.
ooh good catch; yeah we're just going to piggyback off of None until we have a reason to differentiate on landlock on the client side (probably when mounts come into play, or something)
There was a problem hiding this comment.
You can also add it to https://developer.hashicorp.com/nomad/integrations by opening a PR in https://developer.hashicorp.com/nomad/integrations
| #### host networking | ||
|
|
||
| If using `host` networking mode, it can be very convenient to bless the | ||
| pledge.com utility with the `cap_net_bind_service` Linux capability. This will |
There was a problem hiding this comment.
| pledge.com utility with the `cap_net_bind_service` Linux capability. This will | |
| `pledge.com` utility with the `cap_net_bind_service` Linux capability. This will |
| requires the `wpath` promise, creating a file requires the `cpath` promise, and | ||
| executing a program requires the `exec` promise. | ||
|
|
||
| #### examples |
There was a problem hiding this comment.
| #### examples | |
| #### Examples |
| cpu = 2000 | ||
| memory = 1024 | ||
| memory_max = 2048 |
There was a problem hiding this comment.
| cpu = 2000 | |
| memory = 1024 | |
| memory_max = 2048 | |
| cpu = 2000 | |
| memory = 1024 | |
| memory_max = 2048 |
shoenig
added
the
backport/website
lgfa29
added
backport/website
Adds documentation for the pledge task driver to the set of Nomad community plugins.