kapitan 0.35.2.dev31__tar.gz → 0.35.2.dev33__tar.gz

{kapitan-0.35.2.dev31 → kapitan-0.35.2.dev33}/.github/workflows/test-build-publish.yml

@@ -150,7 +150,9 @@ jobs:
           verbose: true
           emoji: false
           job-summary: true
-          custom-pytest: mise exec -- uv run pytest -n auto
+          # pytest-xdist has known hangs/crashes on Python 3.14 (issue #1289/#1313);
+          # run serially on 3.14 until upstream fix is available.
+          custom-pytest: ${{ matrix.python-version == '3.14' && 'mise exec -- uv run pytest' || 'mise exec -- uv run pytest -n auto' }}
           custom-arguments: '-q'
           click-to-expand: true
           report-title: 'Kapitan tests'

{kapitan-0.35.2.dev31 → kapitan-0.35.2.dev33}/Makefile

@@ -109,6 +109,13 @@ test_coverage: test_python
 	@echo "===== Running Coverage Report ====="
 	$(UV_RUN) coverage report
 
+# Regenerate golden compiled snapshots for inventory backend examples
+.PHONY: refresh-inventory-backend-goldens
+refresh-inventory-backend-goldens:
+	@echo "===== Refreshing Inventory Backend Example Golden Snapshots ====="
+	uv run python scripts/refresh_inventory_backend_goldens.py
+	@echo "Golden snapshots refreshed. Review git diff before committing."
+
 # Build Docker image
 .PHONY: build_docker
 build_docker:

{kapitan-0.35.2.dev31 → kapitan-0.35.2.dev33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.35.2.dev31
+Version: 0.35.2.dev33
 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.35.2.dev33/docs/pages/inventory/classes.md

@@ -0,0 +1,208 @@
+---
+title: "Kapitan Inventory Classes: Reusable Configuration Fragments"
+description: "Learn how Kapitan classes let you compose reusable YAML configuration fragments and import them into targets and other classes."
+---
+
+# :kapitan-logo: **Kapitan Inventory Classes**
+
+## Usage
+
+The next thing you want to learn about the inventory are [**classes**]. A class is a yaml file containing a fragment of yaml that we want to import and merge into the inventory.
+
+**Classes** are *fragments* of yaml: feature sets, commonalities between targets. **Classes** let you compose your [**Inventory**](introduction.md) from smaller bits, eliminating duplication and exposing all important parameters from a single, logically organised place. As the [**Inventory**](introduction.md)  lets you reference other parameters in the hierarchy, [**classes**] become places where you can define something that will then get referenced from another section of the inventory, allowing for composition.
+
+**Classes** are organised under the [`inventory/classes`] directory substructure.
+They are organised hierarchically in subfolders, and the way they can be imported into a [**target**](targets.md) or other [**classes**] depends on their location relative to the [`inventory/classes`] directory.
+
+
+### Importing classes
+
+To import a class from within another file of the [**Inventory**](introduction.md), you can follow these instructions:
+
+* take the file path relative to the `inventory/classes/` directory
+* remove the `.yml` file extension
+* replace `/` with `.`
+
+For example, this will import the class `inventory/classes/applications/sock-shop.yaml`
+
+```yaml
+classes:
+- applications.sock-shop
+```
+
+### Wildcard class patterns
+
+Class entries may also be glob patterns that expand to the matching set of
+classes discovered under `inventory/classes/`. This avoids having to list
+each class individually when the set is large or grows over time
+(see [issue #1084](https://github.com/kapicorp/kapitan/issues/1084)).
+
+!!! warning "Opt-in required"
+    Wildcard expansion is **disabled by default**.  You must pass
+    `--enable-class-wildcards` on the `kapitan compile` or `kapitan inventory`
+    command (or set `enable-class-wildcards: true` under the
+    `[inventory_backend]` section of `.kapitan`) to activate it.
+
+    The flag is intentionally opt-in because inventories may contain glob
+    metacharacters in class names for legitimate reasons — for example a class
+    file literally named `config[html].yml`, or Reclass references that include
+    `?` such as `${?some_parameter}`.  Without the flag those entries are passed
+    through unchanged to the backend, which handles them normally.
+
+```yaml
+classes:
+  - "*"             # all classes (top-level and nested) — quote required
+  - clusters.*      # all classes whose dotted name starts with 'clusters.'
+  - apps.dev-*      # all classes under apps/ whose basename starts with 'dev-'
+  - "*.dev-*"       # any class with a 'dev-...' segment in any subdir
+```
+
+Supported glob characters are `*`, `?`, `[` and `]` (standard
+[`fnmatch`](https://docs.python.org/3/library/fnmatch.html) syntax).
+
+**Pattern semantics:**
+
+* Patterns are matched against the **full dotted class name** using
+  `fnmatch`. There is no special-case based on whether a pattern contains
+  `.`. For example, `dev-*` matches only top-level classes named
+  `dev-...`; to match `apps.dev-api` you must write `apps.dev-*` or
+  `*.dev-*`.
+* Class entries that look like Reclass / Kapitan parameter references —
+  any string containing `${` and `}`, including `${var}` and `${?var}` —
+  are passed through to the backend unchanged, even if they contain a
+  glob metacharacter such as `?`. The wildcard expander cannot resolve
+  such references; the backend handles them after class inheritance.
+  Notably, this also means that pattern expansion isn't supported in
+  class includes that use Reclass references.
+
+**Exact-match precedence:**
+
+When `--enable-class-wildcards` is on, the expander first checks whether a
+`classes:` entry exactly matches an existing class name. If it does, the entry
+is treated as a literal include even if the name contains glob metacharacters.
+Only entries that do **not** match any existing class and that contain
+metacharacters are expanded as patterns.
+
+This means:
+
+* A class file literally named `config[html].yml` can still be included with
+  `- config[html]`. It will be treated as an exact class name, not as a
+  character-class pattern.
+* If you want `config[html]` to act as a pattern that matches `configh`,
+  `configt`, `configm`, `configl`, you would need to remove the literal class
+  file so there is no exact match.
+
+**Deterministic lexicographic ordering:**
+
+Each pattern expands to a **lexicographically sorted** list of matches at
+the position of the pattern in the `classes:` list, giving deterministic
+output.
+
+!!! warning "Override order depends on class names"
+    Lexicographic order is deterministic but can be surprising.  For example,
+    a pattern `*.base` that matches both `config.base` and `defaults.base`
+    will always expand to `[config.base, defaults.base]` because `c < d`.
+    Whether `config.base` or `defaults.base` "wins" in a merge depends on the
+    backend's evaluation order.
+
+    **Adding a new class that matches an existing pattern can change the
+    include order of previously matched classes.**  For example, if you later
+    add `alpha.base`, the expansion of `*.base` becomes
+    `[alpha.base, config.base, defaults.base]`, shifting the indices of
+    `config.base` and `defaults.base`.  If another part of your inventory
+    depends on those indices (unlikely but possible with some backends), the
+    behavior changes.
+
+    When wildcard expansion order is critical, design class names carefully.
+    A safe convention is to use **numeric prefixes** that sort in the desired
+    precedence order:
+
+    ```yaml
+    classes:
+      - app.00-defaults
+      - app.10-config
+      - app.90-overrides
+    ```
+
+    This ensures that `app.*` always expands in the intended order regardless
+    of what other `app.*` classes are added later.
+
+    Avoid wildcards when merge order is critical and you cannot control
+    class naming conventions.
+
+* Duplicates (across exact entries and pattern expansions) are removed,
+  preserving the first occurrence.
+* A pattern that matches **no** classes raises an inventory error, unless
+  `--ignore-class-not-found` is set, in which case the unmatched pattern is
+  silently dropped (mirroring the behavior of exact missing class names).
+
+**Symlink handling:**
+
+Wildcard expansion materializes a temporary copy of the inventory tree using
+`shutil.copytree(..., symlinks=True)`.  Symlinks that point to targets
+**inside** the inventory tree are preserved and resolve correctly.  Relative
+symlinks that point **outside** the inventory tree (a common pattern when
+pulling in external modules, e.g. with Commodore) are rewritten to absolute
+paths in the materialized copy so they continue to work.
+
+!!! note
+    `discover_classes` follows directory symlinks during class discovery, so
+    classes inside symlinked directories are discoverable.  External directory
+    symlinks are rewritten to absolute paths in the materialized copy, which
+    also makes their contents discoverable.
+
+!!! warning "`ignore_class_notfound_regexp` interaction"
+    Wildcard expansion happens before the inventory backend processes missing
+    classes.  If you use `ignore_class_notfound_regexp` in your reclass
+    configuration, the regex is evaluated against each **expanded class name**, not
+    against the original pattern string.  If you rely on regex-based skipping of
+    pattern-like entries, you may need to adjust your regex or use
+    `--ignore-class-not-found` instead.
+
+Wildcard expansion happens before the backend resolves inheritance, and works
+both in target files and in nested class files.
+
+**Backend-specific notes:**
+
+* The omegaconf backend's class-file resolver currently only looks for `.yml`
+  files (a pre-existing limitation unrelated to wildcards).  Wildcard
+  expansion correctly discovers `.yaml` classes, but omegaconf will fail to
+  load them.
+
+
+## Definition
+
+Let's take a look at the `common` class which appears in the example above:
+
+As explained, because the **`common.yaml`** is directly under the **`inventory/classes`** subdirectory, it can be imported directly into a target with:
+
+```yaml
+classes:
+- common
+```
+
+If we open the file, we find another familiar yaml fragment.
+
+!!! example "`inventory/classes/common.yml`"
+
+    ```yaml
+    classes:
+    - kapitan.common
+
+    parameters:
+      namespace: ${target_name}
+      target_name: ${_reclass_:name:short}
+    ```
+
+Notice that this class includes an import definition for another class, `kapitan.common`. We've already learned this means that kapitan will import a file on disk called `inventory/classes/kapitan/common.yml`
+
+You can also see that in the `parameters` section we now encounter a new syntax which unlocks another powerful inventory feature: [parameter interpolation](parameters_interpolation.md)!
+
+---
+
+## Next steps
+
+- Learn how to define environments and deployments with [Kapitan inventory targets](targets.md).
+- Understand how to reference values across classes and targets with [parameter interpolation](parameters_interpolation.md).
+- Explore [advanced inventory features](advanced.md) such as wildcard classes and inventory backends.
+- See how classes power [input types](../input_types/introduction.md) like [Jsonnet](../input_types/jsonnet.md) and [Jinja](../input_types/jinja.md).

{kapitan-0.35.2.dev31 → kapitan-0.35.2.dev33}/examples/kubernetes/inventory/targets/all-glob.yml

@@ -3,6 +3,9 @@ classes:
   - common
   - component.namespace
 
+  # Exact class names work as before. When --enable-class-wildcards is
+  # passed, you can also use patterns such as "cluster.*" or "dev-*"
+  # which auto-expand to all matching classes under inventory/classes/.
   - cluster.minikube
 
 parameters:

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/common.yml

@@ -0,0 +1,13 @@
+---
+parameters:
+  target_name: ${_kapitan_.name.short}
+
+  app_name: omegaconf-test
+  environment: dev
+  namespace: default
+  cluster: minikube
+  replicas: 1
+
+  kapitan:
+    vars:
+      target: ${target_name}

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/deferred.yml

@@ -0,0 +1,38 @@
+---
+parameters:
+  # Deferred parentkey resolver demonstration
+  # parentkey resolves at definition location, not merge destination
+  deployment_template:
+    name: \${parentkey:}
+    namespace: ${namespace}
+    labels:
+      app.kubernetes.io/name: \${parentkey:}
+      app.kubernetes.io/instance: ${target_name}
+
+  deployments:
+    web-app: ${merge:${deployment_template}, ${web_app_overrides}}
+    api-service: ${merge:${deployment_template}, ${api_service_overrides}}
+
+  web_app_overrides:
+    replicas: 2
+
+  api_service_overrides:
+    replicas: 3
+
+  # Custom resolver with _root_ context access
+  secrets:
+    db_password: ${with_root:database,password}
+
+  # Uppercase custom resolver
+  uppercase_test:
+    env_upper: ${upper:${environment}}
+    cluster_upper: ${upper:${cluster}}
+
+  # Capitalize custom resolver (camelCase)
+  capitalize_test:
+    camel_name: ${capitalize:${app_name}}
+
+  # String extraction custom resolvers
+  demo_name: omegaconf-demo
+  suffix_test: ${get_suffix:${demo_name}}
+  substr_test: ${get_substr:${demo_name}}

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/empty.yml

@@ -0,0 +1,6 @@
+---
+# Intentionally empty class to test null/empty handling
+classes:
+parameters:
+  empty_test:
+    loaded: true

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/functions.yml

@@ -0,0 +1,60 @@
+---
+parameters:
+  # Test list resolver: convert dict to list of single-key dicts
+  list_input:
+    item1: first
+    item2: second
+  list_result: ${list:${list_input}}
+
+  # Test yaml resolver: dump nested structure to YAML string
+  yaml_source:
+    level1:
+      level2: nested_value
+  yaml_result: ${yaml:yaml_source}
+
+  # Test default resolver: provide fallback when key is missing
+  default_result: ${default:missing_key,fallback_value}
+
+  # Test access resolver: access a key with dots in the name
+  "dotted.key": accessed_value
+  access_result: ${access:dotted.key}
+
+  # Test boolean algebra resolvers
+  bool_and: ${and:true,true,false}
+  bool_or: ${or:false,true,false}
+  bool_not: ${not:true}
+  bool_equal: ${equal:${environment},dev}
+
+  # Test fullkey and key resolvers (evaluated in nested context)
+  key_test:
+    full_name: ${fullkey:}
+    simple_name: ${key:}
+
+  # Test write resolver: write resolved content to another location
+  write_source:
+    copied: true
+    nested:
+      value: written_value
+  write_result: ${write:written_target,write_source}
+
+  # After write, this should be populated
+  written_target:
+    placeholder: before_write
+
+  # Test nested function composition
+  nested_func: ${upper:${concat:hello,world}}
+
+  # Test parentkey in non-deferred context
+  parentkey_test:
+    name: ${parentkey:}
+
+  # Test if with non-string condition
+  if_numeric: ${if:${replicas},has_replicas}
+
+  # Test dict-like merge result behavior
+  dict_merge_result:
+    a: 1
+    b: 2
+
+  kapitan:
+    compile: []

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/init/init.yml

@@ -0,0 +1,5 @@
+---
+# Omegaconf init class: loaded automatically when the parent directory is included
+parameters:
+  init_value: from_init
+  init_common: true

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/init.yml

@@ -0,0 +1,8 @@
+---
+# This class demonstrates the init class feature.
+# When 'features.init' is included, omegaconf loads features/init/init.yml
+classes:
+  - features.init
+
+parameters:
+  init_child: true

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/interpolation.yml

@@ -0,0 +1,34 @@
+---
+parameters:
+  # Standard dot-notation interpolation
+  interpolated: ${app_name}
+
+  # Nested interpolation (interpolation inside interpolation)
+  nested_key: environment
+  nested_interpolated: ${${nested_key}}
+
+  # Escaped interpolation using backslash (deferred - resolved in second pass)
+  deferred_value: \${app_name}
+
+  # Escaped interpolation using escape resolver (preserved as literal string)
+  escaped_value: ${escape:app_name}
+
+  # Interpolation used in string composition
+  full_name: ${app_name}-${environment}
+
+  # Reference to another parameter path
+  ref_value: ${namespace}
+
+  # Conditional with false condition (should produce empty dict)
+  feature_disabled: false
+  conditional_false: ${if:${feature_disabled},should_not_appear}
+
+  # Escape must not resolve even when content matches a real key
+  escaped_real_key: ${escape:environment}
+
+  # Relative path resolver with nested structures
+  nested_config:
+    database:
+      host: db.${cluster}.local
+      port: 5432
+    connection_string: postgresql://${relpath:nested_config.database.host}:${relpath:nested_config.database.port}/mydb

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/merge.yml

@@ -0,0 +1,63 @@
+---
+parameters:
+  # Base objects for merge demonstration
+  base_service:
+    type: ClusterIP
+    port: 80
+    protocol: TCP
+    labels:
+      managed-by: kapitan
+
+  service_override:
+    port: 8080
+    target_port: 8080
+
+  # Merge resolver usage
+  merged_service: ${merge:${base_service}, ${service_override}}
+
+  # Deep merge demonstration
+  base_config:
+    level1:
+      key_a: value_a
+      key_b: value_b
+
+  config_override:
+    level1:
+      key_b: overridden_b
+      key_c: value_c
+
+  merged_config: ${merge:${base_config}, ${config_override}}
+
+  # List concatenation in merge
+  base_list:
+    items:
+      - item1
+      - item2
+
+  list_override:
+    items:
+      - item3
+      - item4
+
+  merged_list: ${merge:${base_list}, ${list_override}}
+
+  # Three-way merge demonstration (replaces the old test_three_way_merge case):
+  # combine defaults + a scalar override + an annotation-style nested addition
+  # to verify that values from all three sources land in the merged result.
+  deployment_defaults:
+    replicas: 1
+    strategy:
+      type: RollingUpdate
+      rollingUpdate:
+        maxSurge: 1
+    pod_annotations:
+      prometheus.io/scrape: "true"
+
+  deployment_custom:
+    replicas: 3
+
+  deployment_annotations:
+    pod_annotations:
+      custom.io/annotation: test-value
+
+  merged_deployment: ${merge:${deployment_defaults}, ${deployment_custom}, ${deployment_annotations}}

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/overwrite.yml

@@ -0,0 +1,17 @@
+---
+parameters:
+  # Base object for override demonstration
+  overwrite_base:
+    key_a: value_a
+    key_b: value_b
+    nested:
+      child: original
+
+  # Override via merge resolver (deep merge)
+  overwrite_override:
+    nested:
+      child: replaced
+    key_c: value_c
+
+  # Demonstrate override behavior
+  overwrite_result: ${merge:${overwrite_base}, ${overwrite_override}}

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/relative.yml

@@ -0,0 +1,4 @@
+---
+parameters:
+  relative_value: from_relative
+  relative_demo: true

kapitan-0.35.2.dev33/examples/omegaconf/inventory/classes/features/remove.yml

@@ -0,0 +1,22 @@
+---
+parameters:
+  omegaconf:
+    remove:
+      - base_component
+      - service_defaults
+      - deployment_defaults
+
+  base_component:
+    name: base
+    namespace: ${namespace}
+    labels:
+      app: base-app
+
+  service_defaults:
+    type: ClusterIP
+    port: 80
+
+  deployment_defaults:
+    replicas: 1
+    strategy:
+      type: RollingUpdate

kapitan-0.35.2.dev33/examples/omegaconf/inventory/resolvers.py

@@ -0,0 +1,56 @@
+import os
+
+
+def double(x: int):
+    """Multiply a number by two."""
+    return x * 2
+
+
+def concat(a: str, b: str):
+    """Concatenate two strings."""
+    return a + b
+
+
+def env_or_default(name: str, default: str):
+    """Read an environment variable with a safe deterministic default."""
+    return os.environ.get(name, default)
+
+
+def get_suffix(name: str):
+    """Extract the last part of a hyphen-separated string."""
+    return name.split("-")[-1]
+
+
+def get_substr(name: str, substr: int = -2):
+    """Extract a specific part of a hyphen-separated string by index."""
+    return name.split("-")[substr]
+
+
+def upper(content: str):
+    """Convert string to uppercase."""
+    return content.upper()
+
+
+def capitalize(input_str: str):
+    """Capitalize hyphenated words (camelCase style)."""
+    parts = input_str.split("-")
+    return parts[0] + "".join([x.capitalize() for x in parts[1:]])
+
+
+def with_root(*args, _root_):
+    """Demonstrate _root_ context access by building a path from target_name."""
+    target_name = _root_.target_name
+    return f"{target_name}/" + "/".join(args)
+
+
+def pass_resolvers():
+    return {
+        "double": double,
+        "concat": concat,
+        "env_or_default": env_or_default,
+        "get_suffix": get_suffix,
+        "get_substr": get_substr,
+        "upper": upper,
+        "capitalize": capitalize,
+        "with_root": with_root,
+    }

kapitan-0.35.2.dev33/examples/omegaconf/inventory/targets/advanced.yml

@@ -0,0 +1,40 @@
+---
+classes:
+  - common
+  - features.merge
+  - features.overwrite
+  - features.init
+  - features.relative
+  - features.deferred
+  - features.empty
+  - features.remove
+  - features.functions
+
+parameters:
+  # Test conditional resolvers
+  feature_enabled: true
+  feature_disabled: false
+
+  conditional_result: ${if:${feature_enabled},enabled_value}
+  conditional_else: ${ifelse:${equal:${environment},dev},development_mode,production_mode}
+
+  # Test arithmetic resolver
+  computed_replicas: ${add:${replicas}, ${replicas}}
+
+  # Test custom resolver (concat)
+  custom_concat: ${concat:hello,world}
+
+  # Test custom resolver (double)
+  custom_double: ${double:${replicas}}
+
+  # Test escape resolver mid-string
+  greeting: "Hello ${escape:USER}, welcome to ${app_name}"
+
+  kapitan:
+    compile:
+      - input_type: jinja2
+        input_paths:
+          - templates/output.yaml.j2
+        output_path: .
+        output_type: yaml
+        suffix_remove: true

kapitan-0.35.2.dev33/examples/omegaconf/inventory/targets/basic.yml

@@ -0,0 +1,14 @@
+---
+classes:
+  - common
+  - features.interpolation
+
+parameters:
+  kapitan:
+    compile:
+      - input_type: jinja2
+        input_paths:
+          - templates/output.yaml.j2
+        output_path: .
+        output_type: yaml
+        suffix_remove: true

kapitan-0.35.2.dev33/examples/omegaconf/inventory/targets/compile-test.yml

@@ -0,0 +1,15 @@
+---
+classes:
+  - common
+  - features.interpolation
+  - features.merge
+
+parameters:
+  kapitan:
+    compile:
+      - input_type: jinja2
+        input_paths:
+          - templates/output.yaml.j2
+        output_path: .
+        output_type: yaml
+        suffix_remove: true