HCP Vault Secrets Centralized secrets lifecycle management for developers. Learn More
Nomad
Nomad Pack

Introduction to Nomad Pack

  • 7min
  • |
  • Nomad

This guide will walk you through basic usage of Nomad Pack, a package manager and templating tool for Nomad.

By the end of this guide, you will know what Nomad Pack does, be able to deploy applications to Nomad using Nomad Pack, and discover packs built by the Nomad community.

What is Nomad Pack

Nomad Pack is a templating and packaging tool used with HashiCorp Nomad.

Nomad Pack is used to:

  • Easily deploy popular applications to Nomad
  • Re-use common patterns across internal applications
  • Find and share job specifications with the Nomad community

Nomad Pack can be thought of as a templating and deployment tool like Levant with the ability to pull from remote registries and deploy multiple resources together, like Helm.

Requirements

  • A Nomad cluster available
  • Nomad cluster address defined in the NOMAD_ADDR environment variable.

Note

If Nomad ACLs are enabled, a token with proper permissions must be defined in the NOMAD_TOKEN environment variable.

Installing Nomad Pack

To use Nomad Pack, clone the repository:

$ git clone https://github.com/hashicorp/nomad-pack

$ git clone git@github.com/hashicorp/nomad-pack

Change directories to the repository and build the executable with make dev.

$ cd ./nomad-pack && make dev

Make the executable available as a command by adding it to your PATH:

$ export PATH="./bin:$PATH"

You can now run nomad-pack.

Basic Use

To get started, run the registry list command to see which packs are available to deploy.

$ nomad-pack registry list

     PACK NAME     |  REF   | METADATA VERSION | REGISTRY |                    REGISTRY URL
-------------------+--------+------------------+----------+-----------------------------------------------------
  fabio            | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  grafana          | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  haproxy          | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  hello_world      | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  loki             | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  nginx            | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  nomad_autoscaler | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  simple_service   | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry
  traefik          | latest | 0.0.1            | default  | github.com/hashicorp/nomad-pack-community-registry

The first time you run registry 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 initializing, Nomad Pack downloads a default registry of packs from the Nomad Pack community registry.

To deploy one of these packs, use the run command. This deploys each job defined in the pack to Nomad. To deploy the hello_world pack, you would run the following command:

$ nomad-pack run hello_world

  Evaluation ID: 67835384-763b-62b0-7c41-eb98a5417e9c
  Job 'hello_world' in pack deployment 'hello_world@latest' registered successfully
Pack successfully deployed. Use --name=hello_world@latest to manage this this deployed instance with run, plan, or destroy

Congrats! You deployed a simple service on Nomad.

Each pack defines a set of variables that can be provided by the user. To get information on the pack and to see which variables can be passed in, run the info command.

$ nomad-pack info hello_world

Pack Name          hello_world
Description        This deploys a simple application as a service with an optional associated consul service.
Application URL    https://learn.hashicorp.com/tutorials/nomad/get-started-run?in=nomad/get-started
Application Author HashiCorp

Pack "hello_world" Variables:
  - "message" (string) - The message your application will render
  - "register_consul_service" (bool) - If you want to register a consul service for the job
  - "consul_service_name" (string) - The consul service name for the hello-world application
  - "consul_service_tags" (list of string) - The consul service name for the hello-world application
  - "job_name" (string) - The name to use as the job name which overrides using the pack name
  - "region" (string) - The region where jobs will be deployed
  - "datacenters" (list of string) - A list of datacenters in the region which are eligible for task placement
  - "count" (number) - The number of app instances to deploy

Values for these variables are provided using the --var flag. Update your pack using the following command:

$ nomad-pack run hello_world --var message=hola

Values can also be provided by passing in a variables file with the -f flag.

$ tee -a ./my-variables.hcl << END
message=bonjour
END

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

To see a list of deployed packs, run the status command

$ nomad-pack status

   PACK NAME  | REGISTRY NAME
--------------+----------------
  hello_world | default

To see the status of the jobs deployed by a pack, run the status command with the pack name.

$ nomad-pack status hello_world

   PACK NAME  | REGISTRY NAME |  DEPLOYMENT NAME   |  JOB NAME   | STATUS
--------------+---------------+--------------------+-------------+----------
  hello_world | default       | hello_world@latest | hello_world | pending

To remove all the resources deployed by a pack, run the destroy command with the pack name.

$ nomad-pack destroy hello_world

Adding Non-Default Pack Registries

When using Nomad Pack, the default registry for packs is the Nomad Pack Community Registry. Packs from this registry will be made automatically available.

You can add more registries by using the registry add command. For instance, if you want to add a registry from GitLab with the alias my_packs, you can run the following command to download the registry and its contents.

$ nomad-pack registry add my_packs gitlab.com/mikenomitch/pack-registry

go-getter URL is gitlab.com/mikenomitch/pack-registry
Registry successfully cloned at /Users/arusso/Library/Caches/nomad/packs/nomad-pack-tmp
Processing pack entries at /Users/arusso/Library/Caches/nomad/packs/nomad-pack-tmp
found pack entry fabio
Processing pack fabio@latest
Updating pack
Removing previous latest
Writing pack to /Users/arusso/Library/Caches/nomad/packs/my_packs/fabio@latest
Loading cloned pack from /Users/arusso/Library/Caches/nomad/packs/my_packs/fabio@latest
Calculating SHA for latest
found pack entry grafana
Processing pack grafana@latest
Updating pack
Removing previous latest
Writing pack to /Users/arusso/Library/Caches/nomad/packs/my_packs/grafana@latest
Loading cloned pack from /Users/arusso/Library/Caches/nomad/packs/my_packs/grafana@latest
Calculating SHA for latest
[...]
  Try running one the packs you just added liked this

    nomad-pack run fabio --registry=my_packs --ref=latest

To view the packs you can now deploy, run the registry list command.

$ nomad-pack registry list
[...]
  fabio                      | latest | 0.0.1            | my_packs | github.com/hashicorp
  grafana                    | latest | 0.0.1            | my_packs | github.com/hashicorp
  haproxy                    | latest | 0.0.1            | my_packs | github.com/hashicorp
  hello_world                | latest | 0.0.1            | my_packs | github.com/hashicorp
  loki                       | latest | 0.0.1            | my_packs | github.com/hashicorp
  nginx                      | latest | 0.0.1            | my_packs | github.com/hashicorp
  nomad_autoscaler           | latest | 0.0.1            | my_packs | github.com/hashicorp
  simple_service             | latest | 0.0.1            | my_packs | github.com/hashicorp
  traefik                    | latest | 0.0.1            | my_packs | github.com/hashicorp

You can deploy packs from this registry with the run command and the alias given to the registry, in this case my_packs.

$ nomad-pack run nginx --registry=my_packs
  Evaluation ID: aaa3c319-1928-7c35-54b0-2358841c0e96
  Job 'nginx' in pack deployment 'nginx@latest' registered successfully
Pack successfully deployed. Use nginx with --ref=latest to manage this this deployed instance with plan, stop, destroy, or info

Nginx successfully deployed.

See the Load Balancing with Nginx tutorial for more information:
https://learn.hashicorp.com/tutorials/nomad/load-balancing-nginx

Next steps

In this tutorial you learned what Nomad Pack does, how to deploy applications to Nomad using Nomad Pack, and how to discover packs built by the Nomad community.

Nomad Pack is valuable when used with official and community packs because it allows you to quickly deploy apps using best practices and leverage communal knowledge. However, many users will also want to write their own packs for internal use.

You can convert your existing Nomad job specifications into reusable packs. To learn more about how packs are structured and how to write your own, see the Writing Packs Guide.

Collection Overview

Nomad Pack

 Next

Writing custom packs

This tutorial also appears in:

  • 8 tutorials
    Create Nomad Job Specifications
    Use HCL to declaratively specify your jobs and their dependencies for deployment into a Nomad cluster.
    • Nomad