Skip to content

Advanced Inventory Features

Target labels

Kapitan allows you to define labels in your inventory, which can then be used to group together targets with similar labels.

For instance you could define the following:

Defines a class to add the customer label to selected targets

inventory/classes/type/customer_project.yml

parameters:
  customer_name: ${target_name} # Defaults to the target_name
  kapitan:
    labels:
      customer: ${customer_name}

Apply the class to the target for customer acme

inventory/targets/customers/acme.yml

classes:
...
- type.customer_project

parameters:
...

You can now selectively compile targets for customer acme using the following (see see Labels for more details )

kapitan compile -l customer=acme
Compiled acme (0.06s)
Compiled acme-documentation (0.09s)

Topics

Topics let targets expose a subset of their parameters so that other targets can aggregate and consume them, without resorting to backend-specific features like reclass exports or expensive inventory_global() scans.

A target opts into a topic by declaring parameters under parameters.kapitan.topics.<topic_name>.parameters:

inventory/targets/target-1.yml

parameters:
  colour: red
  kapitan:
    topics:
      colours:
        parameters:
          colour: ${colour}

inventory/targets/target-2.yml

parameters:
  colour: blue
  kapitan:
    topics:
      colours:
        parameters:
          colour: ${colour}

Kapitan aggregates participating targets into a single topic view of the shape {parameters: {targets: {<target_name>: <topic_parameters>}}}. The topics() function is available to every input type (kadet, jinja2, jsonnet). Call it without arguments to get the full mapping of all topics, or with a name to get a single topic.

kadet (components/painter/__init__.py)

from kapitan.inputs.kadet import topics

def main():
    target_colours = {}
    for target, parameters in topics("colours").parameters.targets.items():
        target_colours[target] = {"colour": parameters.colour}
    return target_colours

jinja2 (components/painter.j2)

{% for target, parameters in topics("colours").parameters.targets.items() %}
{{ target }}:
  colour: {{ parameters.colour }}
{% endfor %}

jsonnet (components/painter.jsonnet)

local kap = import "lib/kapitan.libjsonnet";
{
  [target]: { colour: params.parameters.colour }
  for target in std.objectFields(kap.topics("colours").parameters.targets)
  for params in [kap.topics("colours").parameters.targets[target]]
}

This compiles into:

target-1:
  colour: red
target-2:
  colour: blue

Topics are inventory-backend agnostic and only collect what each target explicitly opts into, avoiding cryptic query expressions and full inventory scans.

Inspecting topics from the CLI

The inventory subcommand has a --topics flag for inspecting the aggregated view without compiling anything.

List all topics

kapitan inventory --topics

Show a single topic

kapitan inventory --topics colours

--topics combines with --pattern to drill into the result and with --flat to produce flat keys:

kapitan inventory --topics colours --pattern parameters.targets
kapitan inventory --topics --flat

Next steps