Format Nomad command output with templates
When using Nomad at an intermediate to advanced level, you'll need to interface with other systems or customize output generated by Nomad. The -t flag is a powerful way to pass a template in Go's text/template format to
several of the Nomad commands that generate output based on the API. This allows
you to filter and customize the output to meet your specific needs.
The commands that allow for the -t flag are:
nomad acl policy listnomad acl token listnomad alloc statusnomad deployment listnomad deployment statusnomad eval statusnomad job deploymentsnomad job historynomad job inspectnomad namespace listnomad node statusnomad plugin statusnomad quota listnomad volume status
This tutorial will teach you how to explore the objects that are returned to the template engine and how to use template syntax to format the output into a custom form.
Prerequisites
This guide assumes the following:
Familiarity with Go's text/template syntax. You can learn more about it in the Learn Go Template Syntax tutorial
That you are running these commands against a Nomad cluster with an active workload. You can create a minimal environment using a dev agent, started with
sudo nomad agent -dev, then running at least one Nomad job. You can usenomad init -shortto create a sample Docker job or provide your own Nomad job.
Note the shell-specific syntax
When using the -t flag, you need to correctly handle string literals based on your shell environment. In a POSIX shell, you can run the following with a single quote:
In a Windows shell (for example, PowerShell), use single quotes but escape the double quotes inside the parameter as follows:
In this tutorial, you can select examples with the proper escaping using the tabs above the snippets.
Start discovering objects
The printf function and the "%#+v" format string are critical tools for you
in exploring an unfamiliar template context.
Run the following command to output the context being passed to the template in Go object format.
The output indicates that the context consists of a list ([]) of pointers
(*) to api.NodeListStub objects. The list will also show one NodeListStub
object per client node in your cluster's server state.
You can explore these api.NodeListStub object by using the range control over
the list.
If you have a lot of client nodes in your cluster state, this output will be
unwieldy. In that case, you can use with and the index function to get the
first list item.
Finally, output Name and Version for each client in the cluster.
Make quiet output
Suppose you want to create a reduced version of the nomad job status output
to show just the running job IDs in your cluster and nothing else.
Nomad will output the job IDs for every running job in your cluster. For example:
Challenge yourself
Allocations have a slightly different shape. How might you create similar output
from the nomad alloc status command? Make sure that your Nomad cluster has at
least one allocation running and then use the printf technique from earlier to
explore the values sent into the template.
Print the context that you are passed from the command using the printf command.
Note that the first thing that you receive is a list ([]) of pointers (*) to
AllocationListStub objects.
Use range to traverse each item in the list.
If you have a lot of allocations running, this could get unwieldy. In that case,
you can use with and the index function to get the first list item.
The fields on the AllocationListStub object that give insight into the running
state of an allocation are DesiredStatus and ClientStatus.
Did you know? The definition of an AllocationListStub object and valid values for the DesiredStatus and ClientStatus are located in Nomad's api package. Take a moment to look at it and see what other information you might be interested in displaying with templates.
Update your template to show items with a DesiredStatus of "run" and a client status of "running" or "pending."
You now have a list of the IDs for all of the allocations running in your Nomad cluster.
Retrieve a template from file
Using the command line to write templates becomes challenging as the template becomes more complex.
By writing a template in its own file, you can use comments, span multiple lines, and indent conditionals in order to make them more readable to you and to other operators.
Consider using some of these techniques to include the template data into the command.
Create a file named running_jobs.tmpl with the following content.
Now, use a subshell to read the file into a variable
Learn more
In this tutorial, you learned how to:
Customize the output of several Nomad commands using Go's text/template syntax.
Use the
printffunction to discover what is available in the template's context.Use a template definition contained in a file as part of the command.
Learn more about templating in other tutorials in the Nomad Templating Collection.