kapitan 0.35.2.dev32__tar.gz → 0.35.2.dev33__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.35.2.dev32
+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.dev32 → 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.dev32 → kapitan-0.35.2.dev33}/kapitan/cli.py

@@ -139,6 +139,21 @@ def build_parser():
         ),
     )
 
+    inventory_backend_parser.add_argument(
+        "--enable-class-wildcards",
+        action="store_true",
+        default=from_dot_kapitan("inventory_backend", "enable-class-wildcards", False),
+        help=(
+            "Enable glob pattern expansion in classes: lists (default: off). "
+            "Patterns such as clusters.*, dev-* and * are expanded to all matching "
+            "class names discovered under inventory/classes/. "
+            "This flag is intentionally opt-in: inventories that contain literal "
+            "glob metacharacters in class names (e.g. config[html]) or Reclass "
+            "references that include ? would be incorrectly treated as patterns "
+            "if expansion were always on."
+        ),
+    )
+
     eval_parser = subparser.add_parser(
         "eval", aliases=["e"], help="evaluate jsonnet file"
     )

{kapitan-0.35.2.dev32 → kapitan-0.35.2.dev33}/kapitan/inputs/cache.py

@@ -92,7 +92,14 @@ class InputCache:
 
     @staticmethod
     def hash_file_digest(fp):
-        return hashlib.file_digest(fp, "blake2b")
+        # hashlib.file_digest is only available from Python 3.11.
+        try:
+            return hashlib.file_digest(fp, "blake2b")
+        except AttributeError:
+            h = hashlib.blake2b(digest_size=64)
+            while chunk := fp.read(8192):
+                h.update(chunk)
+            return h
 
     def dump_output(self, output_obj, fp):
         return pickle.dump(output_obj, fp)

{kapitan-0.35.2.dev32 → kapitan-0.35.2.dev33}/kapitan/inventory/backends/omegaconf/__init__.py

@@ -246,7 +246,7 @@ class OmegaConfInventory(Inventory):
         )
 
     def migrate(self):
-        migrate(self.inventory_path)
+        migrate(self.original_inventory_path)
 
     def resolve_targets(self, targets: list[OmegaConfTarget] = None) -> None:
         if not targets:

{kapitan-0.35.2.dev32 → kapitan-0.35.2.dev33}/kapitan/inventory/inventory.py

@@ -37,8 +37,24 @@ class Inventory(ABC):
         ignore_class_not_found=False,
         initialise=True,
         target_class=InventoryTarget,
+        enable_class_wildcards: bool = False,
     ):
-        self.inventory_path = inventory_path
+        # Pre-expand wildcard class entries (kapicorp/kapitan#1084) into a
+        # temporary mirror of the inventory tree so all backends see only
+        # concrete class names.  Expansion is opt-in (enable_class_wildcards
+        # defaults to False) to avoid breaking inventories that contain
+        # literal glob metacharacters in class names or Reclass references
+        # that happen to include ``?``.  The original path is preserved for
+        # callers that need to operate on the user's on-disk inventory (e.g.
+        # ``migrate()``).
+        from kapitan.inventory.wildcards import materialize_expanded_inventory
+
+        self.original_inventory_path = inventory_path
+        self.inventory_path = materialize_expanded_inventory(
+            inventory_path,
+            ignore_class_not_found=ignore_class_not_found,
+            enable_wildcards=enable_class_wildcards,
+        )
         self.compose_target_name = compose_target_name
         self.targets_path = os.path.join(self.inventory_path, "targets")
         self.classes_path = os.path.join(self.inventory_path, "classes")

kapitan-0.35.2.dev33/kapitan/inventory/wildcards.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+
+# Copyright 2026 The Kapitan Authors
+# SPDX-FileCopyrightText: 2026 The Kapitan Authors <kapitan-admins@googlegroups.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Wildcard expansion for inventory ``classes:`` lists.
+
+Implements the feature requested in kapicorp/kapitan#1084: allow class
+entries such as ``*``, ``clusters.*`` or ``dev-*`` to be expanded into the
+matching set of concrete class names before the inventory backend resolves
+inheritance.
+
+Backend-agnostic strategy: when any target or class file contains wildcard
+entries in its ``classes:`` list, we materialize a temporary copy of the
+inventory tree with those entries pre-expanded. The chosen inventory backend
+(reclass, reclass-rs, omegaconf) is then pointed at the materialized path
+and never has to know about wildcards.
+"""
+
+from __future__ import annotations
+
+import atexit
+import fnmatch
+import logging
+import os
+import shutil
+import tempfile
+from typing import Iterable
+
+import yaml
+
+from kapitan.errors import InventoryError
+
+
+logger = logging.getLogger(__name__)
+
+
+GLOB_METACHARACTERS = frozenset("*?[")
+YAML_EXTENSIONS = (".yml", ".yaml")
+
+
+def is_pattern(name: str) -> bool:
+    """Return True if ``name`` contains any glob metacharacter."""
+    return isinstance(name, str) and any(c in GLOB_METACHARACTERS for c in name)
+
+
+def _looks_like_reclass_reference(entry: str) -> bool:
+    """Return True if ``entry`` looks like a Reclass / Kapitan parameter
+    reference such as ``${some_var}`` or ``${?optional_var}``.
+
+    Such entries must never be treated as glob patterns: they are resolved
+    by the inventory backend after class inheritance has been applied, and
+    the wildcard expander has no way to resolve them.
+    """
+    if not isinstance(entry, str):
+        return False
+    return "${" in entry and "}" in entry
+
+
+def discover_classes(classes_path: str) -> list[str]:
+    """Return a sorted, deduplicated list of class names found under
+    ``classes_path``.
+
+    Class names are derived from the relative path of each YAML file:
+
+    * ``classes/common.yml``        -> ``common``
+    * ``classes/clusters/prod.yml`` -> ``clusters.prod``
+    * ``classes/foo/init.yml``      -> ``foo`` (reclass ``init`` convention)
+    * ``classes/init.yml``          -> ``init`` (root-level init is a real class)
+
+    Hidden files/directories (names starting with ``.``) and non-YAML files
+    are ignored.
+
+    .. note:: ``followlinks=True`` is used so symlinked component directories
+       (common in Commodore) are traversed.  Circular symlinks are detected
+       and pruned automatically.
+    """
+    found: set[str] = set()
+    if not os.path.isdir(classes_path):
+        return []
+
+    visited_dirs: set[str] = set()
+    for root, dirs, files in os.walk(classes_path, followlinks=True):
+        real_root = os.path.realpath(root)
+        if real_root in visited_dirs:
+            # Circular symlink detected — prune to avoid infinite recursion.
+            dirs[:] = []
+            continue
+        visited_dirs.add(real_root)
+        dirs[:] = [d for d in dirs if not d.startswith(".")]
+        for filename in files:
+            if filename.startswith("."):
+                continue
+            name, ext = os.path.splitext(filename)
+            if ext not in YAML_EXTENSIONS:
+                continue
+            relpath = os.path.relpath(root, classes_path)
+            parts: list[str] = [] if relpath in (".", "") else relpath.split(os.sep)
+            if name == "init":
+                # foo/init.yml -> "foo" (keep parent), but classes/init.yml -> "init"
+                if not parts:
+                    parts = ["init"]
+            else:
+                parts.append(name)
+            found.add(".".join(parts))
+
+    return sorted(found)
+
+
+def _matches(pattern: str, available: Iterable[str]) -> list[str]:
+    """Return sorted class names from ``available`` that match ``pattern``.
+
+    Patterns are always matched against the **full dotted class name** using
+    :func:`fnmatch.fnmatchcase`.  No special-case is made for patterns that
+    do or do not contain ``.``: ``dev-*`` matches only top-level class names
+    starting with ``dev-``, and ``*.dev-*`` is required to match
+    ``apps.dev-api`` and similar nested classes.  Keeping the rule boring
+    avoids surprises and makes the documentation simple.
+    """
+    return sorted(c for c in available if fnmatch.fnmatchcase(c, pattern))
+
+
+def _add_if_new(entry: str, seen: set[str], out: list[str]) -> bool:
+    """Append ``entry`` to ``out`` if it has not been seen before.
+
+    Returns ``True`` if the entry was added, ``False`` if it was a duplicate.
+    """
+    if entry in seen:
+        return False
+    seen.add(entry)
+    out.append(entry)
+    return True
+
+
+def expand_class_patterns(
+    class_entries: list,
+    available_classes: Iterable[str],
+    ignore_class_not_found: bool = False,
+) -> list[str]:
+    """Expand wildcard ``class_entries`` against ``available_classes``.
+
+    * Exact (non-pattern) entries are kept in their original position and
+      passed through unchanged so the underlying inventory backend can
+      apply its own missing-class handling.
+    * Entries that exactly match an existing class name are treated as
+      literal includes even if they contain glob metacharacters (e.g.
+      ``config[html]``).  This preserves backward compatibility for
+      inventories that have literal metacharacters in class names.
+    * Entries that look like Reclass / Kapitan parameter references
+      (``${var}``, ``${?var}``) are passed through unchanged even if they
+      contain a glob metacharacter, because they must be resolved by the
+      backend after class inheritance.
+    * Wildcard entries are replaced in-place by their lexicographically
+      sorted set of matches.
+    * Duplicates (across exact and expanded entries) are removed,
+      preserving the first occurrence.  This matches reclass behavior;
+      other backends may already deduplicate too.
+    * An unmatched pattern raises :class:`InventoryError` unless
+      ``ignore_class_not_found`` is set.
+    """
+    available_list = list(available_classes)
+    available_set = set(available_list)
+    seen: set[str] = set()
+    out: list[str] = []
+
+    for entry in class_entries:
+        # Defensive: skip non-string entries.  Malformed YAML or backend
+        # preprocessing can produce integers, None, or booleans in classes:.
+        if not isinstance(entry, str):
+            continue
+
+        # Reclass references are always preserved verbatim.
+        if _looks_like_reclass_reference(entry):
+            _add_if_new(entry, seen, out)
+            continue
+
+        # Exact match takes precedence over pattern expansion.  If a class
+        # with this exact name exists, treat it as a literal include even
+        # when the name contains glob metacharacters (e.g. "config[html]").
+        if entry in available_set:
+            _add_if_new(entry, seen, out)
+            continue
+
+        # Non-pattern entries that don't match an existing class are passed
+        # through unchanged so the backend can apply its own missing-class
+        # handling.
+        if not is_pattern(entry):
+            _add_if_new(entry, seen, out)
+            continue
+
+        matches = _matches(entry, available_list)
+        if not matches and not ignore_class_not_found:
+            raise InventoryError(
+                f"Class pattern '{entry}' did not match any classes in inventory."
+            )
+        for match in matches:
+            _add_if_new(match, seen, out)
+
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Backend-agnostic pre-expansion: materialize an inventory tree with
+# wildcard ``classes:`` entries already expanded.
+# ---------------------------------------------------------------------------
+
+
+def _safe_load_yaml_text(text: str, path: str = ""):
+    try:
+        return yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        if path:
+            logger.warning(
+                "Skipping wildcard scan for %s: invalid YAML (%s)", path, exc
+            )
+        return None
+
+
+def _files_with_wildcards(inventory_path: str) -> list[str]:
+    """Return list of YAML files under ``inventory_path/{targets,classes}``
+    whose ``classes:`` list contains at least one wildcard entry.
+
+    A cheap text-level pre-filter skips full YAML parsing for files that
+    contain no glob metacharacter at all.  This is only a heuristic: many
+    inventories contain ``*``, ``[`` or ``?`` in parameter values (e.g.
+    AWS ARNs, secret references, YAML anchors) so the pre-filter can
+    still have a high false-positive rate.  Correctness does not depend
+    on the pre-filter; any file that survives it is parsed and validated.
+    """
+    out: list[str] = []
+    for sub in ("targets", "classes"):
+        base = os.path.join(inventory_path, sub)
+        if not os.path.isdir(base):
+            continue
+        visited_dirs: set[str] = set()
+        for root, dirs, files in os.walk(base, followlinks=True):
+            real_root = os.path.realpath(root)
+            if real_root in visited_dirs:
+                # Circular symlink detected — prune to avoid infinite recursion.
+                dirs[:] = []
+                continue
+            visited_dirs.add(real_root)
+            dirs[:] = [d for d in dirs if not d.startswith(".")]
+            for filename in files:
+                if filename.startswith("."):
+                    continue
+                if not filename.endswith(YAML_EXTENSIONS):
+                    continue
+                path = os.path.join(root, filename)
+                # Fast path: if the raw file contains no glob metacharacter
+                # there cannot be a wildcard class entry to expand.
+                try:
+                    with open(path, encoding="utf-8") as fh:
+                        text = fh.read()
+                except OSError:
+                    continue
+                if not any(c in text for c in GLOB_METACHARACTERS):
+                    continue
+                data = _safe_load_yaml_text(text, path)
+                if not isinstance(data, dict):
+                    continue
+                classes = data.get("classes")
+                if not isinstance(classes, list):
+                    continue
+                if any(
+                    is_pattern(c) and not _looks_like_reclass_reference(c)
+                    for c in classes
+                ):
+                    out.append(path)
+    return out
+
+
+def _fix_relative_symlinks(src_root: str, dest_root: str):
+    """After copying an inventory tree, rewrite relative symlinks that
+    point outside the copied tree so they resolve correctly.
+
+    ``shutil.copytree(..., symlinks=True)`` preserves symlink target paths
+    verbatim.  A relative symlink such as ``ext -> ../../external_classes``
+    that resolved from the original inventory will break in the temporary
+    copy because the relative base has moved.  We walk the copied tree and
+    convert any such broken relative symlink to an absolute path based on
+    the original target's resolved absolute path.
+    """
+    for dirpath, dirs, filenames in os.walk(dest_root, followlinks=False):
+        # Process both file and directory symlinks.
+        for name in list(dirs) + filenames:
+            dest_link = os.path.join(dirpath, name)
+            if not os.path.islink(dest_link):
+                continue
+            target = os.readlink(dest_link)
+            if os.path.isabs(target):
+                continue
+            # Does the relative target resolve from the new location?
+            dest_resolved = os.path.normpath(os.path.join(dirpath, target))
+            if os.path.exists(dest_resolved):
+                continue
+            # Try to resolve from the corresponding original location.
+            rel_dir = os.path.relpath(dirpath, dest_root)
+            src_link = os.path.join(src_root, rel_dir, name)
+            # Defensive: these should never be hit because the dest symlink
+            # was already verified to be a relative symlink above, and
+            # shutil.copytree(..., symlinks=True) preserves the link type.
+            if not os.path.islink(src_link):
+                continue
+            src_target = os.readlink(src_link)
+            if os.path.isabs(src_target):
+                continue
+            src_resolved = os.path.normpath(
+                os.path.join(os.path.dirname(src_link), src_target)
+            )
+            if os.path.exists(src_resolved):
+                # Rewrite to absolute so the materialized inventory works.
+                os.remove(dest_link)
+                os.symlink(src_resolved, dest_link)
+
+
+def materialize_expanded_inventory(
+    inventory_path: str,
+    ignore_class_not_found: bool = False,
+    enable_wildcards: bool = False,
+) -> str:
+    """If ``enable_wildcards`` is True and any target/class YAML under
+    ``inventory_path`` contains wildcard class entries, return a path to a
+    temporary copy of the inventory with those entries pre-expanded.
+    Otherwise return ``inventory_path`` unchanged.
+
+    ``enable_wildcards`` defaults to ``False`` so that inventories with
+    literal glob metacharacters in class names (e.g. ``config[html]``) or
+    Reclass references that contain ``?`` are never treated as patterns
+    unless the caller has explicitly opted in.
+
+    The temporary directory is registered for cleanup via :mod:`atexit`.
+    """
+    if not enable_wildcards:
+        return inventory_path
+
+    if not os.path.isdir(inventory_path):
+        return inventory_path
+
+    files_to_expand = _files_with_wildcards(inventory_path)
+    if not files_to_expand:
+        return inventory_path
+
+    classes_path = os.path.join(inventory_path, "classes")
+    available = discover_classes(classes_path)
+
+    tmp_root = tempfile.mkdtemp(prefix="kapitan_inv_")
+    atexit.register(shutil.rmtree, tmp_root, ignore_errors=True)
+
+    base_name = os.path.basename(os.path.normpath(inventory_path)) or "inventory"
+    dest = os.path.join(tmp_root, base_name)
+    shutil.copytree(inventory_path, dest, symlinks=True)
+
+    # Fix relative symlinks that now point outside the temp tree.
+    _fix_relative_symlinks(inventory_path, dest)
+
+    for src in files_to_expand:
+        rel = os.path.relpath(src, inventory_path)
+        out_path = os.path.join(dest, rel)
+        with open(out_path, encoding="utf-8") as fh:
+            data = _safe_load_yaml_text(fh.read())
+        if not isinstance(data, dict):
+            continue
+        original = data.get("classes") or []
+        data["classes"] = expand_class_patterns(
+            original, available, ignore_class_not_found=ignore_class_not_found
+        )
+        with open(out_path, "w", encoding="utf-8") as fh:
+            yaml.safe_dump(data, fh, sort_keys=False)
+
+    logger.debug(
+        f"Materialized inventory with wildcard class expansion at {dest} "
+        f"(rewrote {len(files_to_expand)} file(s))"
+    )
+
+    return dest