Jerakia logo

Jerakia Lookups

Lookup blocks define where and how to source the data. At a minmum a lookup block must specify a datasource to pass the request to. Data sources can optionally take a hash of arguments. Look at each datasource’s documentation for information on what options they support.

A policy can contain many lookups and each one is evaluated in order within the policy.

Supported methods are

  • datasource, {opts} data source with corresponding options
  • invalidate disable this lookup
  • scope return the scope object
  • output_filter add an output handler to this request
  • stop Do not proceed to the next lookup if this lookup is deemed valid, regardless of whether data is returned
  • confine Confine this lookup to a set of criteria
  • exclude Exclude this lookup if the criteria is matched

Example

Here is an example of a Jerakia lookup contained within a policy

policy :default do
  lookup :main do
    datasource :file, {
      :format => :yaml,
      :extension => 'yaml',
      :docroot => '/etc/jerakia/data',
      :searchpath => [
        scope[:certname],
        scope[:environment],
        'global',
      ]
    },
  end
end

Defining Lookups

Lookups are defined inside policies using the lookup method.

lookup :main do
end

The lookup method also supports the :use flag to load plugins

lookup :main, :use => :hiera do
end

Lookup Methods

datasource

The datasource option takes a datasource name as the first argument and options to be passed to the datasource as a hash in the second argument

datasource :<datasource>, { :opt => value, :opt => value }

Example:

datasource :file, {
  :format => :yaml,
  :docroot => '/var/lib/jerakia/data',
  :searchpath => [
    scope[:certname],
    scope[:environment],
    'global',
  ]
},

Learn more about datasources

confine and exclude

The confine and exclude lookup methods allow you to specify when a lookup should be run or should be skipped. When you have multiple lookups defined in a policy you may not want to always run all lookups.

Both arguments take a subject as the first argument and the criteria as the second argument.

For example, to only run a lookup if the namespace matches apache you can specify

lookup :special do
   ...
   confine request.namespace[0], "apache"
end

The second argument can be a regex, and multiple criteria can be passed in as an array, eg:

lookup :special do
  ...
  confine request.namespace[0], [
    /website_.*/,
    "apache",
    "php"
  ]
end

The exclude method has the oposite effect of confine and will cause the lookup to be run unless the condition matches.

invalidate

Calling the invalidate method will cause Jerakia to skip this lookup and proceed to the next one (if applicable)

stop

The stop method will prevent Jerakia from running any more lookups after the containing lookup, however, it only has effect if the containing lookup is valid. If the lookup is invalidated with confine, exclude or invalidate then Jerakia will proceed to the next lookup.

output_filter

The output_filter lookup method will send the data returned from the datasource to the response filter specified as the first argument, for example, if you are using the eyaml encryption response filter, then you need an output_filter method to enable that in your lookup

lookup :main do
  ...
  output_filter :encryption
end

scope

The scope method returns the key/value scope data from the requestor as a hash.

scope[:value]

Further examples

Here is an example of a much more complex policy that contains a dedicated lookup via an HTTP datasource that is used when configuring PHP or Apache, but a default file based lookup for everything else.

policy :default do

  lookup :webserver do
    datasource :http, {
      :host   => '127.0.0.1',
      :port   => 5984,
      :output => "json",
      :paths  => [
        "/configuration/#{scope[:environment]}",
        "/configuration/global",
      ]
    }

    confine request.namespace[0], [
      "apache",
      "php",
    ]

    stop
  end

  lookup :main, do
    datasource :file, {
      :format     => :yaml,
      :docroot    => "/var/lib/jerakia",
      :searchpath => [
        "hostname/#{scope[:fqdn]}",
        "environment/#{scope[:environment]}",
        "common"
      ],
    }
  end
end

In this example, the first lookup will be evaluated for any lookup that is in the apache or php namespace. The stop method tells Jerakia to only use this lookup if the criteria of confine deem this to be a valid lookup. If the namespace does not match, then this lookup is ignored and the next lookup, main, will be used.