Nomad Pack

Nomad Pack includes helper functions based on Go's netip package for handling IP addresses and ports.

Warning: The parsing functions (parseAddr and parseAddrPort) will cause a template rendering error if provided with an invalid address. To prevent template failure, always validate the address using validAddr or validAddrPort before attempting to parse it.

Nomad Packs allow you to parameterize your Nomad jobs using variables. When running a pack, you can override these variables using the --var flag. This allows you to customize deployments (e.g., changing a message, scaling instance counts, or specifying datacenters) without modifying the underlying job template.

To override a variable, use the following syntax: nomad-pack run <pack-name> --var <variable-name>="<value>"

nomad-pack run {{.PackName}} --var message="Hola Mundo!"

Nomad Pack provides a set of functions to customize how data structures are dumped using the Spew package. To use them, you must first initialize a configuration state using customSpew. This state can then be passed through various with* functions to modify specific printer settings before finally calling .Sdump to output the result.

Workflow:

1. Call customSpew to get a default spew.ConfigState.
2. Pipe the state through customization functions (e.g., withIndent, withSortKeys).
3. Call .Sdump on the resulting state with the object you want to inspect.

[[ $cs := ( customSpew | withIndent "  " ) ]][[ $cs.Sdump . ]]

Packs are organized into registries. While the Nomad Pack Community Registry is available by default, you can add custom registries (e.g., from Git or GitLab) to access private or specialized packs.

• registry add <name> <url>: Adds a new registry to your local configuration.
• registry list: Lists all currently configured registries.
• list: Lists available packs (use registry list to see which registries are providing them).

# Add a custom registry
nomad-pack registry add example gitlab.com/mikenomitch/pack-registry

# List all configured registries
nomad-pack registry list

# List available packs
nomad-pack list

To remove the resources (such as Nomad jobs) deployed by a pack, use the destroy command followed by the pack name.

If you used the --name flag during deployment to assign a specific deployment name, you must provide that same --name to the destroy command.

If your deployment used variable overrides (--var) that affect the job names within the pack, you must include those same variable overrides in the destroy command to target a specific job. If you omit the variable overrides, nomad-pack will attempt to destroy all jobs associated with that pack and deployment name.

# Basic destroy
nomad-pack destroy hello_world

# Destroying a pack deployed with a specific name
nomad-pack destroy hello_world --name hola-mundo

# Destroying a specific job instance using variable overrides
nomad-pack destroy hello_world --name hola-mundo --var job_name=spanish

Use make commands to manage the local development lifecycle:

1. Bootstrap dependencies: Run make bootstrap to install required tools.
2. Verify code integrity: Run make check to validate Go modules and sums.
3. Build the binary: Run make dev to compile the project. This generates an executable at ./bin/nomad-pack.
4. Execute the binary: Run the local binary directly to test it (e.g., ./bin/nomad-pack -h).

# Install required tools
make bootstrap

# Check Go mod and Go sum
make check

# Build a binary from local code (outputs to ./bin/nomad-pack)
make dev

# Run your code
./bin/nomad-pack -h

To test a pack during development, pass the local directory path to the nomad-pack commands (run, plan, render, info, stop, or destroy). When using a local path, the pack is treated as having a dev registry and dev reference.

# Run the pack from the current directory
nomad-pack run .

To ensure the spinner does not interfere with standard output (e.g., when redirecting stdout to a file), set the spinner's writer to os.Stderr using spinner.WithWriter().

s := spinner.New(spinner.CharSets[11], 100*time.Millisecond, spinner.WithWriter(os.Stderr))
s.Suffix = " Encrypting data..."
s.Start()
// Now stdout can be safely used for actual data
fmt.Println(os.Stdout, ciphertext)

A pack directory within a registry must contain the following files:

• README.md: Human-readable description and dependency info.
• metadata.hcl: Pack metadata (name, version, description, etc.).
• variables.hcl: HCL definitions for variables used in templates.
• templates/: A subdirectory containing .nomad.tpl files for rendering jobspecs.
• CHANGELOG.md (Optional): Version history.
• outputs.tpl (Optional): Defines text to print upon successful deployment.

Note: Pack dependencies must be declared in metadata.hcl using dependency blocks.

To develop on Nomad Pack locally, ensure you have the following dependencies installed:

• Golang
• Git
• Make

Additionally, ensure that $GOHOME/bin is included in your $PATH environment variable.