kapitan 0.36.2.dev2__tar.gz → 0.36.2.dev3__tar.gz

{kapitan-0.36.2.dev2 → kapitan-0.36.2.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.36.2.dev2
+Version: 0.36.2.dev3
 Summary: Generic templated configuration management for Kubernetes, Terraform and other things
 Project-URL: Homepage, https://kapitan.dev
 Project-URL: Repository, https://github.com/kapicorp/kapitan

{kapitan-0.36.2.dev2 → kapitan-0.36.2.dev3}/docs/pages/core_concepts.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Core Concepts"
+title: "Kapitan Core Concepts: Inventory, Targets & Inputs"
 description: "Learn how Kapitan organizes configuration with inventory, targets, classes, and input types to generate Kubernetes, Terraform, and infrastructure manifests."
 ---
 
@@ -11,7 +11,7 @@ description: "Learn how Kapitan organizes configuration with inventory, targets,
 
 ```mermaid
     graph LR
-        TARGETS ==  **kapitan compile** ==> INPUT_TYPES
+        TARGETS == "`**kapitan compile**`" ==> INPUT_TYPES
         INPUT_TYPES --> TARGETS_OUTPUT
         TARGETS_OUTPUT --> GENERATED_FILES
 

kapitan-0.36.2.dev3/docs/pages/inventory/backends.md

@@ -0,0 +1,77 @@
+---
+title: "Kapitan Inventory Backends: reclass vs reclass-rs vs OmegaConf"
+description: "Compare Kapitan inventory backends — reclass, reclass-rs, and OmegaConf — and learn which to choose for speed, compatibility, and features."
+---
+
+# :kapitan-logo: **Alternative Inventory Backends**
+
+Kapitan's [**inventory**](introduction.md) is pluggable: you can swap the engine
+that loads and resolves it without rewriting a single `class`, `target`, or
+`parameter`. Three backends ship with Kapitan, and they differ in three things
+that matter when you choose one — **speed**, **interpolation syntax**, and **which
+features they support**.
+
+* `reclass` (**default**): the original Kapitan inventory (see [reclass](https://github.com/kapicorp/reclass)). Bundled — nothing to install.
+* `reclass-rs`: a Rust drop-in replacement, much faster (see [reclass-rs](reclass-rs.md)). Optional extra.
+* `omegaconf`: an [OmegaConf](https://github.com/omry/omegaconf)-based alternative with custom resolvers (see [omegaconf](omegaconf.md)). Optional extra, **experimental**.
+
+## Which backend should I use?
+
+- **Stay on `reclass`** unless you have a reason to switch. It is the default, the most mature, and supports every Kapitan inventory feature.
+- **Switch to `reclass-rs`** when inventory rendering is slow — large inventories with heavy parameter interpolation in class includes. It is a **drop-in**: same syntax, no inventory changes, just faster ([benchmarks](reclass-rs.md#performance-comparison)). Check the [feature gaps](#feature-support) first.
+- **Choose `omegaconf`** only if you specifically want its resolver toolkit (`${merge:}`, `${escape:}`, conditionals, custom Python resolvers). It uses **different interpolation syntax**, so it is **not** a drop-in — existing inventories need [migration](omegaconf.md#migration-from-reclass). It is **experimental**.
+
+## Comparison
+
+| | `reclass` (default) | `reclass-rs` | `omegaconf` |
+|---|---|---|---|
+| **Install** | bundled | `pip install kapitan[reclass-rs]` | `pip install kapitan[omegaconf]` |
+| **Maturity** | stable, default | stable | **experimental** (pre-release dep) |
+| **Implementation** | Python | Rust | Python |
+| **Speed** | baseline | **much faster** on large inventories ([benchmarks](reclass-rs.md#performance-comparison)) | comparable to reclass |
+| **Interpolation syntax** | colon paths `${a:b:c}` | colon paths `${a:b:c}` (same as reclass) | dotted paths `${a.b.c}` + resolvers |
+| **Drop-in for reclass?** | — | ✅ yes, same syntax | ❌ no, needs [migration](omegaconf.md#migration-from-reclass) |
+| **List merge (class include)** | extend / concatenate | extend / concatenate | extend **+ de-duplicate** (`EXTEND_UNIQUE`) |
+| **Custom resolvers** | ❌ | ❌ | ✅ `${merge:}`, `${escape:}`, `${if:}`, user-defined, … |
+| **Inventory queries** (`$[...]`, exports) | ✅ | ❌ not supported | ❌ not supported |
+
+!!! warning "List-merge semantics differ"
+    `reclass` / `reclass-rs` **concatenate** lists on class inclusion (duplicates
+    kept). `omegaconf` de-duplicates (`EXTEND_UNIQUE`) during class merge — but
+    its `${merge:...}` resolver keeps duplicates (`EXTEND`). If you switch
+    backends, a list that previously had repeated entries may change. Verify
+    list-valued parameters after migrating.
+
+## Switching backend
+
+Pick the backend by either:
+
+* (**recommended**) setting it in the [.kapitan config file](../commands/kapitan_dotfile.md):
+
+```yaml
+global:
+  inventory-backend: reclass-rs
+```
+
+* or passing `--inventory-backend=<backend>` on the `kapitan` command line.
+
+## Feature support
+
+`reclass` is the reference: it supports the full feature set.
+
+`reclass-rs` is a drop-in, but a few reclass options are **not implemented yet**
+(known gaps, sourced from the [upstream reclass-rs project](https://github.com/projectsyn/reclass-rs)
+— may change between versions):
+
+- inventory queries (`$[...]` expressions)
+- `allow_none_override: false` (effectively pinned to `true`; Kapitan's default is `true`, so the default case works)
+- storage types other than `yaml_fs` (`yaml_git`, `mixed`)
+
+It also has minor behavioral divergences in non-compatible modes (e.g. `null` in
+nested references, dots in `compose_node_name`) — see the upstream README. If a
+feature you rely on is missing,
+[open an issue upstream](https://github.com/projectsyn/reclass-rs/issues).
+
+`omegaconf` supports a different feature set — see
+[Differences from Reclass](omegaconf.md#differences-from-reclass) for what is and
+isn't supported, plus its resolver catalogue.

{kapitan-0.36.2.dev2 → kapitan-0.36.2.dev3}/docs/pages/inventory/introduction.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Inventory"
+title: "Kapitan Inventory: Classes, Targets & Parameters"
 description: "Learn how Kapitan inventory uses targets, classes, and parameters to model reusable infrastructure configuration across environments."
 ---
 
@@ -74,6 +74,59 @@ By combining [**target**](targets.md) and [**classes**](classes.md), the **Inven
 
 ---
 
+## How the inventory is built
+
+Before any input type runs, **Kapitan** turns a target file and its class graph
+into a single, fully-resolved set of `parameters`. Understanding the order of
+these steps explains *why* a value overrides another, and *when* a `${...}`
+reference gets its value.
+
+```mermaid
+flowchart TD
+    A["Read target<br/>targets/production.yml"] --> B{"wildcards<br/>enabled?"}
+    B -->|"--enable-class-wildcards"| C["Expand glob patterns<br/>into matching class names"]
+    B -->|default| D
+    C --> D["Resolve each class to a file<br/>classes/kapicorp/common.yml → kapicorp.common"]
+    D --> E["Load classes recursively<br/>(depth-first: a class's own<br/>classes are loaded before it)"]
+    E --> F["Deep-merge parameters in include order<br/>later entries override earlier;<br/>the target's own parameters win last"]
+    F --> G["Resolve ${...} interpolation<br/>against the fully-merged parameters"]
+    G --> H["Final resolved inventory<br/>handed to the compile phase"]
+
+    style F fill:#fff3e0
+    style G fill:#e1f5fe
+```
+
+1. **Read target** — the target file is the entry point. Its `classes:` list
+   drives everything that follows.
+2. **Expand wildcards** *(optional)* — with
+   [`--enable-class-wildcards`](classes.md#wildcard-class-patterns), glob
+   patterns in `classes:` are expanded to concrete class names *before* the
+   backend sees them. Without the flag, entries pass through unchanged.
+3. **Resolve & load classes** — each class name maps to a file under
+   `inventory/classes/`. Classes are loaded **recursively and depth-first**: a
+   class's own `classes:` are loaded before the class itself, so foundational
+   data lands first.
+4. **Merge parameters** — `parameters` blocks are **deep-merged** in the order
+   classes are encountered. **Later entries override earlier ones**, and the
+   target's own `parameters` are merged last, giving them the highest
+   precedence. This is why list position in `classes:` matters (see the
+   [override-order warning](classes.md#wildcard-class-patterns) for wildcards).
+5. **Resolve interpolation** — only **after** the full merge are `${...}`
+   references resolved, against the final merged values. A reference therefore
+   sees the *winning* value regardless of which class defined it.
+6. **Final inventory** — the resolved `parameters` are handed to the
+   [compile phase](../input_types/introduction.md#phases-of-the-compile-command),
+   which feeds each input type.
+
+!!! note "Backend differences"
+    The merge-then-resolve model above is the shared mental model. The
+    [`reclass`](backends.md) and `reclass-rs` backends follow it directly;
+    the [`omegaconf`](omegaconf.md) backend uses a **double-pass** resolution to
+    support escaped interpolations. Test inventory changes against every backend
+    you support.
+
+---
+
 ## Next steps
 
 - Learn how to define environments and deployments with [Kapitan inventory targets](targets.md).

kapitan-0.36.2.dev2/docs/pages/inventory/backends.md

@@ -1,12 +0,0 @@
-# :kapitan-logo: **Alternative Inventory Backends**
-
-We provide pluggable backend alternatives for the Inventory:
-
-* `reclass`(**default**): The original kapitan inventory  (see [reclass](https://github.com/kapicorp/reclass))
-* `reclass-rs`: The Rust drop in replacement (see [reclass-rs](reclass-rs.md))
-* `omegaconf`: An alternative inventory solution based on [Omegaconf](https://github.com/omry/omegaconf) (see [omegaconf](omegaconf.md))
-
-You can switch the backend to by:
-
-* (**recommended**) Define the backend in the [.kapitan config file](../commands/kapitan_dotfile.md).
-* Passing the `--inventory-backend=backend` command line option when calling `kapitan`.