Nomad Pack detailed usage

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

In this tutorial, 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 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

Registry management

The Introduction to Nomad Pack tutorial 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.

$ 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 add command and Nomad Pack will re-download the registry and replace the contents.

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

Next steps

In this tutorial 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 Writing Custom Packs tutorial.