urga

A terminal UI for HashiCorp Nomad. One binary, no config to write, no browser.

What it does

• Lists jobs, allocations, the tasks of an allocation or of the whole namespace, task groups, deployments, evaluations, services, namespaces, variables, clients, node pools, servers, volumes, CSI plugins and the ACL objects.
• Watches the deploy of a job with w: the newest evaluation, the deployment and its allocations, until it ends.
• Updates the screen when the cluster changes, using the Nomad event stream, and shows the stream itself on :events, for the namespace, or for one job or allocation.
• Counts on one screen what needs attention: dead jobs, failed allocations, tasks that restart or run out of memory, clients that are down or draining, blocked evaluations and failed deployments, and opens the list of each with one key.
• Shows task logs and the files of an allocation, follows them as they grow, and reads a log further back than its last 64 KiB. Shows the log of a task from every allocation of a job at once.
• Edits a job in your editor and shows the plan before it submits anything.
• Shows the values of variables, hidden until you ask for them, and who holds a variable as a lock, and releases a lock left held. Creates, edits and deletes variables with check-and-set.
• Creates, edits and deletes namespaces.
• Shows the versions of a job, reverts to any of them, tags them, and marks them stable or unstable.
• Explains why a job is not placed, has the scheduler evaluate it again, and places its failed allocations again without waiting for their delay. Shows what an evaluation planned for each group, and opens the allocations it placed or changed.
• Lists the launches of periodic and parameterized jobs, shows when a periodic job runs next, runs it now, and dispatches a parameterized job with its meta and payload.
• Starts, stops, scales and restarts jobs and allocations, restarts every task of an allocation with its prestart and sidecar tasks, restarts and signals single tasks, opens a shell in a task, and runs a command in a task and keeps what it printed.
• Drains clients, shows their CPU and memory over time, marks the ones that are full, shows when the identity of a client expires and renews it. Purges clients that are down, stopped jobs, and collects the garbage of a client or of the whole cluster.
• Shows the health of the servers and how many the cluster can lose.
• Shows how the scheduler places work, and edits it with check-and-set.
• Lists the scaling policies and shows what the autoscaler did with the count of each group.
• Lists the jobs and the clients of a node pool.
• Works in read-only mode, and with several named clusters.
• Says when a newer urga is out, what it changed and how to update.
• Finds anything in the cluster by its name or ID, in every namespace.
• Creates, edits and deletes ACL tokens, policies, roles, auth methods and binding rules.

Install

On macOS, with Homebrew:

brew install ingvarch/tap/urga

On Debian, Ubuntu, Fedora or RHEL, download the .deb or .rpm package from the releases page and install it:

sudo apt install ./urga_*_amd64.deb
sudo dnf install ./urga-*.x86_64.rpm

On Arch Linux install from the AUR:

# https://aur.archlinux.org/packages/urga
yay -S urga

For other systems (Linux, macOS, Windows and FreeBSD, on amd64 and ARM), download an archive from the same page, or install with Go:

go install github.com/ingvarch/urga/cmd/urga@latest

To build from source:

make build && ./bin/urga

Quick start

urga uses the same environment variables as the nomad CLI. No configuration file is needed.

export NOMAD_ADDR=https://nomad.example.com:4646
export NOMAD_TOKEN=<your token>
urga

Press ? for help, : to open another screen, / to filter and q to quit.

Documentation

• Configuration: environment variables, flags, read-only mode, the editor, and the saved session.
• Named clusters: an optional settings file for several clusters, and switching between them.
• Keys and commands: the command line, the filter, and the keys of every screen.
• Jobs: jobs, task groups and their scaling, editing and plans, versions, evaluations and deployments.
• Allocations and tasks: allocations, every task of the namespace with :tasks, checks, task actions, logs and files.
• Clients, servers and other resources: clients, servers, the scheduler, namespaces, services, variables and node pools.
• Storage: CSI volumes, dynamic host volumes and CSI plugins.
• Access control: ACL tokens, policies, roles, auth methods and binding rules.

Contributing

How to build urga, run the checks and send a change is in CONTRIBUTING.md. Security problems are reported privately, see SECURITY.md.

License

MIT, see LICENSE. The release archives and packages also carry THIRD_PARTY_NOTICES, the licenses of the modules urga is built from.

Nomad is a trademark of HashiCorp. urga is an independent project and is not affiliated with or endorsed by HashiCorp.

About the name

An urga is a Mongolian catch pole: a long wooden shaft with a loop of rope at the end. A rider holds it out at a gallop and takes the one horse he wants out of a herd of hundreds that is still moving.

A cluster is that herd. This is what you reach into it with.