Lookup Tables
A lookup table answers the question "attribute A has the value x, which value does attribute B get?" from a list, instead of one rule per value. It is meant for long lists: thousands of entries are fine.
You find them under Modules > Lookup Tables.
The table
Give the table a Name (templates refer to it by that name), choose its Mode and paste the list into Table, for example a block copied out of a spreadsheet:
location;datacenter;owner
site-a;DC1;team-a
site-b;DC2;team-b
site-c;DC3;team-c
- The first line names the columns, the same way as for a
pasted list: lower cased, everything that is not a letter,
digit or underscore becomes
_. - In the mode Key / Value the first column is the key, every other column is a value (see Mode).
- The separator is detected from the first line: tab, semicolon, comma or
|. - Empty lines are skipped.
- Up to 100000 entries per table.
The list view shows how many keys a table has and its columns.
Mode: Key / Value or Table
Key / Value (the default) is for lookup(): the first column is the
key, every other column is a value. The table needs at least two columns,
and a key that appears twice cannot be saved, since it would not be clear
which line wins.
Table is a plain list of rows: any number of columns, also a single
one, and values may repeat. It is meant for looping over it with
lookup_rows(), for example to build
a request body. lookup() works on it as well and takes the first line
with the key.
site
site-a
site-b
Using it: lookup()
lookup() works in every Jinja field (Custom Attributes, Rewrite Attributes,
export rules, ...). In Custom Attributes and Rewrite Attributes the
Jinja help button below the value field lists your tables and their
columns and inserts the lookup() call for you.
{{ lookup('datacenters', location) }}
{# the second column (datacenter) of the line whose key is the value of location #}
{{ lookup('datacenters', location, 'owner') }}
{# the column owner instead #}
{{ lookup('datacenters', location, default='unknown') }}
{# 'unknown' when there is nothing to find #}
Signature: lookup(table, key, column=None, default='').
The key is compared exactly (surrounding spaces are ignored). An unknown
table, key or column, an empty cell or a host without the key attribute all
give default.
Looping over a table: lookup_rows()
lookup_rows('datacenters') returns every line of the table as a dict of
column name to value, in the order of the table, in both modes. An unknown
table gives an empty list. It is meant for building a list or a request body out of the
whole table, for example the POST body of a
REST API import.
{% for row in lookup_rows('datacenters') %}{{ row.location }}: {{ row.owner }}
{% endfor %}
A Table of one column works the same way:
{% for row in lookup_rows('sites') %}{{ row.site }},{% endfor %}
Example: set the datacenter of a location
Hosts carry a location, and their datacenter attribute is unknown for
some of them. Those should get the datacenter of their location from the list
above.
Create a Global Custom Attribute rule:
- Condition: attribute
datacenterisunknown - Outcome: attribute name
datacenter, value{{ lookup('datacenters', location, default='unknown') }}
Hosts with another datacenter are not touched. The same can be done without a condition in a single template:
{% if datacenter == 'unknown' %}{{ lookup('datacenters', location) }}{% else %}{{ datacenter }}{% endif %}
Changes
Saving or deleting a table resets the cached rule outcomes of the hosts, as a rule change does, so the next export uses the new values. A process that is already running (the web interface, a long export) reads a changed table again within a minute.
Lookup tables are part of the Rule Import/Export.