Concepts

Configuration Hierarchy

Commodore uses the Kapitan inventory, which uses reclass, to provide a hierarchical configuration lookup.

Commodore doesn’t assume how your configuration hierarchy will look like. Instead, the hierarchy can be configured within the hierarchy itself. Commodore only prepares the entrypoint of the hierarchy to build upon.

See inventory hierarchy for further details.

Inventory

The Commodore inventory is really a Kapitan inventory.

Commodore collects the contents of the inventory from different Git repositories. Those Git repositories are either global (to the Syn instance) or in the scope of a customer. A customer may have one or more configuration repositories for their different Project Syn-managed platforms. The inventory Git repositories aren’t versioned, as they always reflect the desired state.

Inventory repositories are cloned directly into the Kapitan inventory directory to make their contents available as inventory classes in Kapitan.

Commodore also makes use of the inventory to manage component repository locations and versions.

Components

Each Commodore component is managed in an individual Git repository and provides all the code which necessary to install some software or tool. The repository name must be named the same as the component.

Each component includes the Kapitan templates (for example Jsonnet), and classes which define how to install the software. The classes must be included somewhere in the Kapitan inventory to install the software.

Components can optionally provide Jsonnet libraries which can be used by other components. To allow Commodore to make component libraries available to other components, they must be placed in directory lib/.

Components can specify Jsonnet dependencies in a jsonnetfile.json in the component’s root directory. Commodore uses jsonnet-bundler to fetch all components' dependencies. Optionally, components can provide a jsonnetfile.jsonnet instead of jsonnetfile.json. If a jsonnetfile.jsonnet is present it will be rendered to jsonnetfile.json before Commodore fetches component dependencies. The jsonnetfile.jsonnet approach is described in more details in the architecture documentation.

Components can define and use postprocessing filters which are applied on the result of the component’s compiled Kapitan catalog. Components define postprocessing filters in the inventory in key parameters.commodore.postprocess.filters. Details of the filter definition format and the postprocessing process can be found in the architecture documentation.

Component parameters expose a limited set of configuration options for the software managed by the component. The component is expected to provide sensible default values for most, if not all, component parameters. One common component parameter, which appears in most components, allows configuring which version of the software will be installed.

A component must define two Kapitan classes, which must be available as class/<component-name>.yml and class/defaults.yml in the component repository.

The class class/<component-name>.yml defines how the component is compiled, and is commonly referred to as the component class. The class class/defaults.yml defines defaults for the component parameters, and is commonly referred to as the component defaults.

Each component repository is cloned into dependencies/, its component class is symlinked to inventory/classes/components/<component-name>.yml and its component defaults is symlinked to inventory/classes/defaults/<component-name>.yml.

Commodore includes all component defaults in the configuration hierarchy before the global defaults (global.common).

Splitting the component defaults into a separate class which gets included early in the configuration hierarchy allows components to provide defaults which are guaranteed to have the lowest priority when resolving the hierarchy.

Component versions and remote repository locations can be specified in the inventory repositories, and versions can be expressed as arbitrary Git tree-ishs.

Cluster Catalog

The cluster catalog contains the rendered manifests generated by Commodore and Kapitan and the Kapitan secret references. The cluster catalog is stored as a Git repository and checked out as catalog/ when Commodore operates on it. Commodore puts the rendered manifests (the Kapitan output) in directory manifests/ in the catalog repository. Secret references are stored in directory refs/ in the catalog repository.

Secret References

Commodore makes use of Kapitan’s secret references mechanism to ensure no plain text secrets are present in the cluster catalog.

At this time, Commodore only supports the Kapitan "Vaultkv" secret type.