From cc6a93905e9352b6d24b788ad16869120b055351 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Fri, 2 May 2025 09:58:41 -0500 Subject: [PATCH 1/3] Add user guide content from Nomad docs site. --- README.md | 171 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 169 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 311439a..3dc350b 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,13 @@ ## Requirements -- [Nomad](https://www.nomadproject.io/downloads.html) v0.9+ +- [Nomad](https://github.com/hashicorp/nomad/releases) v0.9+ - [Go](https://golang.org/doc/install) v1.11+ (to build the provider plugin) - [Singularity](https://github.com/singularityware/singularity) v3.1.0+ ## Building The Driver -Clone repository on your prefered path +Clone repository on your preferred path ```sh git clone git@github.com:sylabs/nomad-driver-singularity @@ -51,3 +51,170 @@ In order to test the provider, you can simply run `make test`. ```sh make test ``` + +## User Guide + +The Singularity Nomad driver provides an interface for using Singularity for +running application containers. + +## 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` - (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` - (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` - (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](https://www.sylabs.io/guides/3.1/user-guide/networking.html). + +## 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` directory. +- [`Singularity`](https://github.com/sylabs/singularity) v3.1.1+ + +## 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`). Refer to + [`Singularity-cache`](https://www.sylabs.io/guides/3.1/user-guide/appendix.html#c) + for more details. + +An example of using these plugin options: + +```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` 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). From 2951715fff049b14f7e0f5c352679e6deea84f03 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Fri, 2 May 2025 10:02:08 -0500 Subject: [PATCH 2/3] Add user guide content from Nomad docs site --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3dc350b..5429c1e 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Code Coverage](https://codecov.io/gh/hpcng/nomad-driver-singularity/branch/master/graph/badge.svg)](https://codecov.io/gh/hpcng/nomad-driver-singularity) [![Go Report Card](https://goreportcard.com/badge/github.com/hpcng/nomad-driver-singularity)](https://goreportcard.com/report/github.com/hpcng/nomad-driver-singularity) -[Hashicorp Nomad](https://www.nomadproject.io/) driver plugin using +[Hashicorp Nomad](https://www.hashicorp.com/en/products/nomad) driver plugin using [Singularity containers](https://github.com/sylabs/singularity) to execute tasks. ## Requirements @@ -185,7 +185,7 @@ The `Singularity` driver requires the following: - The Singularity driver binary placed in the `plugin_dir` directory. - [`Singularity`](https://github.com/sylabs/singularity) v3.1.1+ -## Plugin Options ((#plugin_options)) +## Plugin Options - `enabled` - The `Singularity` driver may be disabled on hosts by setting this option to `false` (defaults to `true`). From 9bf50d911090bb3101edc502be4a265e8ac87306 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Fri, 2 May 2025 10:04:05 -0500 Subject: [PATCH 3/3] update heading levels in user guide section --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5429c1e..b3979df 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ make test The Singularity Nomad driver provides an interface for using Singularity for running application containers. -## Task Configuration +### Task Configuration ```hcl task "lolcow" { @@ -172,11 +172,11 @@ The `Singularity` driver supports the following configuration in the job spec: } ``` -## Networking +### 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](https://www.sylabs.io/guides/3.1/user-guide/networking.html). -## Client Requirements +### Client Requirements The `Singularity` driver requires the following: @@ -185,7 +185,7 @@ The `Singularity` driver requires the following: - The Singularity driver binary placed in the `plugin_dir` directory. - [`Singularity`](https://github.com/sylabs/singularity) v3.1.1+ -## Plugin Options +### Plugin Options - `enabled` - The `Singularity` driver may be disabled on hosts by setting this option to `false` (defaults to `true`). @@ -207,14 +207,14 @@ plugin "nomad-driver-Singularity" { Please note the plugin name should match whatever name you have specified for the external driver in the `plugin_dir` directory. -## Client Attributes +### 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 +### 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).