HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Nomad
Nomad Home

Nomad Pack advanced usage

In the Nomad Pack overview guide you learned about Nomad Pack, how to deploy applications with it, and how to discover community packs.

In this guide, you will learn about more advanced usage including:

  • Generating a variable file
  • Rendering a Pack
  • Advanced run options
  • Planning with plan
  • Registry management

Generating a variable file

You can pass in variables to a pack with a variables file.

$ nomad-pack run hello_world -f ./my-variables.hcl

The generate var-file command can generate variable files from a pack.

$ nomad-pack generate var-file hello_world -o ./my-variables.hcl

You can also use the path to a pack instead of a pack name.

$ nomad-pack generate var-file ./my-local-pack -o ./my-variables.hcl

Rendering a Pack

At times, you may wish to use Nomad Pack to render jobspecs, but you will not want to immediately deploy these to Nomad.

This can be useful when writing a pack, debugging deployments, integrating Nomad Pack into a CI/CD environment, or if you have another mechanism for handling Nomad deploys.

The render command takes the same --var and --var-file flags that run takes.

The --to-dir flag determines the directory where the rendered templates will be written.

You can pass the --render-output-template flag to additionally render the output template. Some output templates rely on a deployment for information. In these cases, the output template may not render with all the necessary information.

$ nomad-pack render hello_world --to-dir ./tmp --var greeting=hola --render-output-template

Advanced run options

To deploy the resources in a pack to Nomad, use the run command.

$ nomad-pack run hello_world

By default, run monitors evaluations and deployments after job submission. If you are running in automation and want the command to return immediately, use the --detach flag.

$ nomad-pack run hello_world --detach

If a target job already exists and was not deployed by Nomad Pack, you can use --deploy-override.

$ nomad-pack run hello_world --deploy-override

When you update a running deployment, Nomad Pack stops jobs that no longer exist in the updated pack definition.

By passing a --name value into run, Nomad Pack deploys each resource in the pack with a metadata value for pack name. If no name is given, the pack name is used by default.

This allows Nomad Pack to manage multiple deployments of the same pack.

$ nomad-pack run hello_world --name hola-mundo

It is also possible to run a local pack directly from the pack directory by passing in the directory instead of the pack name. This can be helpful while developing a pack.

nomad pack run .

Planning with plan

If you want see details on how Nomad Pack will deploy a pack but are not ready to immediately deploy the pack, run the plan command.

This invokes Nomad in a dry-run mode using the Nomad Plan API endpoint.

nomad-pack plan hello_world

Similar to run, plan takes the --name flag to look for packs deployments with that name. Nomad Pack uses the pack name by default.

nomad-pack plan hello_world --name hola-mundo

The plan command also takes the --var and -f flags like the run command.

nomad-pack plan hello_world -f ./my-variables.hcl --var greeting=hallo

The plan command also supports --deploy-override when you want to plan over an existing non-pack job.

nomad-pack plan hello_world --deploy-override

Reading HCL diagnostics

When Nomad Pack reports HCL parsing errors, the message includes filename, line, and column ranges. For example, variables.hcl:3,3-7 identifies the exact location to inspect.

Registry management

The Introduction to Nomad Pack guide explains the basics of adding to and listing packs in the registry. The following section provides additional details on registry management.

Initialization and directory structure

The first time you run list, Nomad Pack will add a nomad/packs directory to your desktop user's cache directory—$XDG_CACHE_DIR on Linux, ~/Library/Caches on macOS, %AppData% on Windows, etc. This folder stores information about cloned registries and their available packs.

During initialization, Nomad Pack downloads a default registry of packs from the Nomad Pack community registry.

The directory structure is as follows:

parent-directories (see above)
└── nomad
    └── packs
        ├── <REGISTRY>
            ├── <REGISTRY-TAG>
                ├── <PACK-NAME@REF>
                    ├── ...files containing pack contents...

Nomad Pack requires the contents of the pack cache directory to work properly, but you should not manually manage or change these files. Instead, you can use the registry commands.

Adding new registries

The registry command includes several sub-commands for interacting with registries.

Add custom registries with the registry add command. Any git based registry supported by go-getter should work.

For example, to add the entire Nomad Pack Community Registry, use the registry add command to download the registry.

$ nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry

Adding an individual pack from a registry

To add a single pack from the registry, use the --target flag.

$ nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry --target=nginx

Adding a registry at a specific commit

To download a single pack or an entire registry at a specific version/SHA, use the --ref flag.

Refs can include slashes, such as pack-name/v0.4.2.

$ nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry --ref=v0.0.1

Removing a registry

To remove a registry or pack from your local cache, use the registry delete command. This command also supports the --target and --ref flags.

$ nomad-pack registry delete community

Updating a registry

To update a registry, use the registry update command.

$ nomad-pack registry update default

Next steps

In this guide you learned how to interact with Nomad Pack in an advanced way. You learned how to generate a variable file, render a pack, use additional run options, use the plan command, and interact with Nomad Pack registries.

The official and community packs available to Nomad Pack are valuable because it allows you to quickly deploy apps using the best practices and leverage the knowledge of the Nomad community.

To learn how to write your own Nomad Packs or convert your existing Nomad job specifications into reusable packs, continue on to the Creating packs guide.

Edit this page on GitHub