RunCommand: write documentation for dynamic commands

This commit is contained in:
Graham Christensen 2021-12-08 12:37:13 -05:00
parent 4ea646130c
commit 6ffc93c01a

View file

@ -30,3 +30,53 @@ Command to run. Can use the `$HYDRA_JSON` environment variable to access informa
command = cat $HYDRA_JSON > /tmp/hydra-output command = cat $HYDRA_JSON > /tmp/hydra-output
</runcommand> </runcommand>
``` ```
### Dynamic Commands
Hydra can optionally run RunCommand hooks defined dynamically by the jobset.
This must be turned on explicitly in the `hydra.conf` and per jobset.
#### Behavior
Hydra will execute any program defined under the `runCommandHook` attribute set. These jobs must have a single output named `out`, and that output must be an executable file located directly at `$out`.
#### Security Properties
Safely deploying dynamic commands requires careful design of your Hydra jobs. Allowing arbitrary users to define attributes in your top level attribute set will allow that user to execute code on your Hydra.
If a jobset has dynamic commands enabled, you must ensure only trusted users can define top level attributes.
#### Configuration
- `dynamicruncommand.enable`
Set to 1 to enable dynamic RunCommand program execution.
#### Example
In your Hydra configuration, specify:
```xml
<dynamicruncommand>
enable = 1
</dynamicruncommand>
```
Then create a job named `runCommandHook.example` in your jobset:
```
{ pkgs, ... }: {
runCommandHook = {
recurseForDerivations = true;
example = pkgs.writeScript "run-me" ''
#!${pkgs.runtimeShell}
${pkgs.jq}/bin/jq . "$HYDRA_JSON"
'';
};
}
```
After the `runcommandHook.example` build finishes that script will execute.