Configure the inventory hierarchy

The Kapitan inventory used by Commodore builds on top of reclass. The Reclass fork used by Kapitan allows to use references in class names. This allows to dynamically build up the configuration hierarchy.

Directory structure

Commodore builds up the Kapitan inventory with the following directory structure:

inventory/
├─ classes/
|  ├─ components/
|  |  └─ … (1)
|  ├─ defaults/
|  |  └─ … (2)
|  ├─ global/ (3)
|  |  ├─ commodore.yml (4)
|  |  └─ …
|  ├─ params/
|  |  └─ cluster.yml (5)
|  └─ <tenant id> (6)
|     └─ …
└─ targets
   ├─ cluster.yml (7)
   └─ … (8)
1 Symlinks pointing to the class files of the components.
2 Symlinks pointing to the default values of the components.
3 Clone of the git repository holding your global configuration hierarchy.
4 Included by the clusters target and thus the starting point for your inventory hierarchy.
5 Holds parameters set by commodore along with cluster facts retrieved from Lieutenant. Included by the clusters target. This file is generated by Commodore.
6 Clone of the git repository holding the configuration hierarchy of the clusters tenant.
7 A Kapitan target for the cluster. Used by Commodore for bootstrapping the component targets.
8 A Kapitan target for each component. This file is generated by commodore.

Available parameters

To build up your configuration hierarchy, include classes in commodore.yml within your global configuration inventory. The following parameters can be used to make your hierarchy dynamic based on cluster facts.

parameters:
  cluster:
    catalog_url: "ssh://git@…" (1)
    name: "c-…" (2)
    tenant: "t-…" (3)
  facts: { … } (4)
1 The git URL of the clusters manifest catalog.
2 The clusters Lieutenant id.
3 The Lieutenant id of the clusters tenant.
4 Dictionary of all the clusters facts set at Lieutenant.

When using to include classes, parameters can not be defined in the same file they’re referenced . They must be defined within files already processed and therefore are higher up in the hierarchy.

Defining the hierarchy

Based on the above, you are free to define your hierarchy according to your needs. The following are examples. They showcase a sensible foundation to start. It also showcases what’s possible. Also take note of the commodore-defaults, a global configuration repository used in tutorials.

From commodore we get the following base hierarchy:

  • Component default parameter values

  • Cluster parameter values

  • commodore.yml within the global configuration repository

Within commodore.yml, we then can include further classes and build up the hierarchy. The hierarchy could then be extended by configurations related to a:

  • Kubernetes distribution

  • Cloud provider

  • Cloud provider region

  • Tenant

  • Cluster

The distribution and cloud provider are the levels to most likely include Commodore components.

Parameter precedence in Reclass

Reclass follows a node centric model where included classes are considered to be parents. Parameters within a class will override the one from included classes. See reclass concepts.

This is somewhat counter intuitive to how Reclass is used in this context. In order to prevent confusion, classes and parameters shouldn’t be defined within the same file. It’s suggested to have parameters defined in dedicated params.yml files.

Examples

commodore.yml
classes:
  - global.distribution.${facts:distribution}
  - global.cloud.${facts:cloud}
  - global.cloud.${facts:cloud}.${facts:region}
  - ${cluster:tenant}.${cluster:name}

Reclass requires parameters to be defined when used in references. When building a hierarchy that has optional parts, one must be creative. You might work with clouds that don’t know the concept of a region. So instead of including the region in commodore.yml, include it only for those clouds that have regions.

commodore.yml
classes:
  - global.distribution.${facts:distribution}
  - global.cloud.${facts:cloud}
  - ${cluster:tenant}.${cluster:name}
cloud/cloud_without_regions.yml
classes: []
cloud/cloud_with_regions.yml
classes:
  - global.cloud.cloud_with_regions.params (1)
  - global.cloud.cloud_with_regions.${facts:region}
1 Parameters for cloud_with_regions are define in a dedicated parameters file. See Parameter precedence in Reclass for why this is.