This tutorial is intended as a quick guide to get set up and familar with Jerakia.
First we need to install Jerakia
To install the latest stable version
You can also install Jerakia using system packages, see Installing Jerakia
Jerakia reads it’s initial configuration from
/etc/jerakia/jerakia.yaml by default. At the very minimal we need to confgure the loglevel information and the locations of the logfile, policy directory and plugin directory.
Note: If you have installed Jerakia from the system packages, then a default configuration file will already exist.
Jerakia policies are containers for lookups. When a lookup is invoked against Jerakia it can select a policy to use, by default, if no policy name is given then Jerakia will look for a policy called
Policy files live within the directory defined in
jerakia.yaml, so let’s create an empty policy. Note that if you installed Jerakia from the system packages, a default policy file should already have been created for you. This tutorial walks you through writing one form scratch.
Jerakia policies contain lookups that run in order.
A lookup must contain, at the very least, a name and a datasource to use for the lookup. The current datasources that ship with Jerakia are
http. The file datasource takes several options, including format and searchpath to define how lookups should be processed. Within the lookup we have access to
scope which contains all the information we need to determine what data should be returned. In Puppetspeak, the scope contains all facts and top-level variables passed from the agent
We will start by using the
file datasource, You can read more about the options available on the File datasource documentation
Inside the policy block that we created earlier, we will now add our first lookup called
Here we have described the
:main lookup to use the datasource
:format refers to which data format to expect files to use, Jerakia can support a number of format handlers that plug into the file datasource, in this case we are using the
:docroot refers to where we store our data files. The
searchpath contains an array of locations, relative to the
:docroot that represents a search hierarchy that will be searched in order for the lookup key
scope object contains information about the requestor that helps determine how we look up the data, in this case, we base the lookup on the
environment of the requestor. More on scope later.
file datasource as configured earlier we can add our data to YAML files under the directory specified in
:docroot, which we set to
It’s recommended that you read Jerakia Lookup Basics to understand the structure and behaviour of a Jerakia lookup
When using the
file datasource, the
:searchpath is evaluated to determine which files to scan and elements of the scope object can be interpolated into the file paths. By default, Jerakia will search for the key in a filename corresponding to the namespace. So, lets review our lookup object from earlier, it has the following settings configured…
If our scope contains the following
Then when we search for the key
port in the
apache namespace (eg: apache::port) then Jerakia will scan the following files until it encounters the key
The astute among you might have noticed that the search is done in a
common directory rather than
common.yaml as you would expect with hiera. To understand why that is the case read File datasource, to explain the functioning and differences between hiera and jerakia. To get the above debug output yourself read the Debug Guide
Let’s start off by adding the port value to our searchpath
jerakia command takes a subcommand as the first attribute, for further information use
To look up the data that we added earlier we can use the following command:
To specify metadata like
puppet facter data, you can run the command in the following form:
Now let’s provide some different data further up in our hierarchy, for example, we shall override
port to be
8099 in our dev environment.
If we run the same query command as before, we expect to get the same output
Remember that the
searchpath gets evaluated from the scope, and since we haven’t provided any scope data there is nothing to match. Let’s repeat this lookup by providing some scope data, in this case, ensuring that the environment is