kapitan 0.35.2.dev21__tar.gz → 0.35.2.dev23__tar.gz

kapitan-0.35.2.dev23/.github/workflows/pex-build-upload.yml

@@ -0,0 +1,91 @@
+---
+name: PEX Build and Upload
+
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows:
+      - Publish Python Package to PyPI
+    types:
+      - completed
+
+jobs:
+  pex_build_publish:
+    runs-on: ubuntu-latest
+    # For workflow_run: only run when the upstream PyPI publish succeeded.
+    # For workflow_dispatch: always run (manual trigger).
+    if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
+    permissions:
+      # Required for softprops/action-gh-release to upload PEX + checksum
+      # assets to the GitHub release page. Only actually used when the tag
+      # upload condition below evaluates to true (release tags only).
+      contents: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Determine release tag
+        id: tag
+        run: |
+          # For workflow_run, github.ref is the default branch — derive the tag
+          # from the triggering workflow's head branch instead.
+          # For workflow_dispatch, use GITHUB_REF_NAME directly.
+          if [ "${{ github.event_name }}" = "workflow_run" ]; then
+            TAG="${{ github.event.workflow_run.head_branch }}"
+          else
+            TAG="${GITHUB_REF_NAME}"
+          fi
+          echo "name=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "Release tag: ${TAG}"
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: |
+            3.10
+            3.11
+            3.12
+            3.13
+            3.14
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - name: Install libraries dependencies
+        run: |
+          uv pip compile \
+            --all-extras \
+            --format=requirements.txt \
+            --output-file=requirements.txt \
+            pyproject.toml
+      - name: Set up Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version: 1.17
+      - name: Build Pex
+        run: |-
+          mkdir -p dist
+          uvx pex '.[gojsonnet,omegaconf,reclass-rs]' -r requirements.txt \
+            --python-shebang='#!/usr/bin/env python3' \
+            --python=python3.11 \
+            --python=python3.10 \
+            --python=python3.12 \
+            --python=python3.13 \
+            --python=python3.14 \
+            -m kapitan \
+            -o dist/kapitan.linux-x86_64.pex
+          dist/kapitan.linux-x86_64.pex --help
+
+      - name: Generate PEX checksum
+        run: |
+          (cd dist && sha256sum kapitan.linux-x86_64.pex) > dist/kapitan.linux-x86_64.pex.sha256
+          echo "PEX checksum:"
+          cat dist/kapitan.linux-x86_64.pex.sha256
+          (cd dist && sha256sum -c kapitan.linux-x86_64.pex.sha256)
+
+      - name: Add linux-x86_64 pex to assets
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
+        if: >-
+          (github.event_name == 'workflow_run' && startsWith(github.event.workflow_run.head_branch, 'v')) ||
+          startsWith(github.ref, 'refs/tags/')
+        with:
+          tag_name: ${{ steps.tag.outputs.name }}
+          files: |
+            dist/kapitan.linux-x86_64.pex
+            dist/kapitan.linux-x86_64.pex.sha256

kapitan-0.35.2.dev23/.github/workflows/python-pypi-publish.yml

@@ -0,0 +1,78 @@
+---
+name: Publish Python Package to PyPI
+
+concurrency:
+  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
+  cancel-in-progress: true
+
+on:
+  workflow_dispatch:
+  release:
+    types: [created]
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for softprops/action-gh-release to upload SBOM + checksum
+      # assets to the GitHub release page. Only actually used when the
+      # "Upload release artifacts" step runs (release events only).
+      contents: write
+      # NOTE:
+      # Remove user/password and uncomment id-token permission once Trusted
+      # Publishing (OIDC) is setup in pypi. See:
+      # https://github.com/pypa/gh-action-pypi-publish
+      # id-token: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: pyproject.toml
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - name: Build and check
+        run: |
+          uv build
+          uvx twine check dist/*
+      - name: Extract version
+        id: version
+        run: |
+          # On release events, use the tag name (stripping any leading 'v').
+          # On workflow_dispatch, fall back to parsing the built wheel filename
+          # (kapitan is not installed in the runner Python after `uv build`).
+          if [ "${{ github.event_name }}" = "release" ]; then
+            VERSION="${GITHUB_REF_NAME#v}"
+          else
+            VERSION=$(python3 -c "import glob, re, sys; m=re.search(r'kapitan-([^-]+)-', glob.glob('dist/kapitan-*.whl')[0]); print(m.group(1)) if m else sys.exit('no wheel found')")
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Detected version: ${VERSION}"
+      - name: Generate SBOM
+        timeout-minutes: 10
+        run: |
+          scripts/generate_sbom.sh "${{ steps.version.outputs.version }}" dist
+      - name: Generate SHA256 checksums
+        timeout-minutes: 5
+        run: |
+          scripts/generate_checksums.sh dist dist/SHA256SUMS
+      - name: Validate checksums
+        timeout-minutes: 5
+        run: |
+          (cd dist && sha256sum -c SHA256SUMS)
+      - name: Upload release artifacts
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
+        with:
+          files: |
+            dist/kapitan-*.whl
+            dist/kapitan-*.tar.gz
+            dist/kapitan-${{ steps.version.outputs.version }}.python.sbom.cdx.json
+            dist/SHA256SUMS
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/.github/workflows/test-build-publish.yml

@@ -161,6 +161,8 @@ jobs:
     name: build ${{ matrix.platform.platform }} image using python ${{ matrix.python-version }}
     needs: [setup, precommit, test, check-changes]
     runs-on: ${{ matrix.platform.runner }}
+    permissions:
+      contents: read
     strategy:
       fail-fast: false
       matrix:
@@ -218,6 +220,9 @@ jobs:
             type=semver,pattern={{major}},suffix=${{ steps.suffix.outputs.python-suffix }}${{ steps.suffix.outputs.platform-suffix }}
           flavor: |
             latest=false
+          labels: |
+            io.kapitan.sbom.format=CycloneDX
+            io.kapitan.sbom.spec-version=1.6
 
       # For default python version, also create tags with -py suffix for compatibility
       - name: Docker meta (py-suffixed tags for default version)
@@ -267,6 +272,54 @@ jobs:
         run: |
           docker run -t --rm local-test --version
 
+      - name: Set up uv
+        if: github.event_name != 'pull_request'
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+
+      - name: Generate Docker SBOM
+        id: docker-sbom
+        if: github.event_name != 'pull_request'
+        timeout-minutes: 10
+        run: |
+          mkdir -p dist
+          PLATFORM_SLUG=$(echo "${{ matrix.platform.platform }}" | tr '/' '-')
+          # On release events use the tag; otherwise fall back to a short SHA so
+          # the artifact filename is still unique and traceable.
+          if [ "${{ github.event_name }}" = "release" ]; then
+            VERSION="${GITHUB_REF_NAME#v}"
+          else
+            VERSION="${GITHUB_SHA::8}"
+          fi
+          SBOM_FILE="dist/kapitan-${VERSION}-py${{ matrix.python-version }}-${PLATFORM_SLUG}-docker.sbom.cdx.json"
+          # Generate SBOM from production+extras deps via uv export.
+          # --all-extras matches the Docker image which installs gojsonnet/omegaconf/reclass-rs.
+          # --no-group test/docs prevents dev tooling from contaminating the SBOM.
+          uv export \
+              --no-dev --no-group test --no-group docs \
+              --all-extras --no-editable \
+              --format requirements-txt --no-hashes | \
+            grep -Ev '^[[:space:]]*(#|\.[[:space:]]*$|$)' | \
+            uvx --from 'cyclonedx-bom>=4,<5' cyclonedx-py requirements \
+              --mc-type application \
+              --of JSON \
+              --output-reproducible \
+              -o "${SBOM_FILE}" -
+          echo "sbom-file=${SBOM_FILE}" >> "$GITHUB_OUTPUT"
+          echo "platform-slug=${PLATFORM_SLUG}" >> "$GITHUB_OUTPUT"
+          echo "Docker SBOM generated: ${SBOM_FILE}"
+
+      - name: Validate Docker SBOM
+        if: github.event_name != 'pull_request'
+        run: scripts/validate_sbom.sh "${{ steps.docker-sbom.outputs.sbom-file }}"
+
+      - name: Upload Docker SBOM artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: docker-sbom-py${{ matrix.python-version }}-${{ steps.docker-sbom.outputs.platform-slug }}
+          path: ${{ steps.docker-sbom.outputs.sbom-file }}
+          retention-days: 1
+
       - name: Push image to DockerHub
         env:
           DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -281,6 +334,35 @@ jobs:
           build-args: |
             PYTHON_VERSION=${{ matrix.python-version }}
 
+  upload-docker-sboms:
+    name: upload Docker SBOMs to release
+    needs: [setup, build]
+    if: github.event_name == 'release'
+    runs-on: ${{ needs.setup.outputs.runner }}
+    permissions:
+      contents: write
+    steps:
+      - name: Download Docker SBOM artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          pattern: docker-sbom-*
+          merge-multiple: true
+          path: dist/sboms
+
+      - name: Verify SBOMs were downloaded
+        run: |
+          count=$(find dist/sboms -name '*.sbom.cdx.json' -type f | wc -l)
+          echo "Found ${count} Docker SBOM(s)"
+          if [ "${count}" -eq 0 ]; then
+            echo "ERROR: no Docker SBOMs downloaded; build artifacts may have expired (retention=1 day)." >&2
+            exit 1
+          fi
+
+      - name: Upload Docker SBOMs to release
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
+        with:
+          files: dist/sboms/*.sbom.cdx.json
+
   build-multi-architecture:
     name: combine platform images for python ${{ matrix.python-version }}
     needs:

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/.pre-commit-config.yaml

@@ -13,6 +13,11 @@ repos:
     hooks:
       - id: end-of-file-fixer
       - id: check-merge-conflict
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+        args: [--severity=warning]
   - repo: https://github.com/rhysd/actionlint
     rev: 'v1.7.7'
     hooks:

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/Dockerfile

@@ -38,7 +38,7 @@ RUN uv sync --locked --all-extras
 
 COPY ./kapitan ./kapitan
 
-RUN uv pip install .[gojsonnet,omegaconf,reclass-rs]
+RUN uv pip install .[gojsonnet,omegaconf,reclass-rs,rapidyaml]
 
 ARG PYTHON_VERSION=3.11
 FROM golang:1 AS go-builder

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.35.2.dev21
+Version: 0.35.2.dev23
 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.dev23/docs/pages/inventory/advanced.md

@@ -0,0 +1,151 @@
+# Advanced Inventory Features
+
+## Target labels
+
+Kapitan allows you to define labels in your inventory, which can then be used to group together targets with similar labels.
+
+For instance you could define the following:
+
+!!! example ""
+
+    Defines a class to add the `customer` label to selected targets
+
+    !!! example "`inventory/classes/type/customer_project.yml`"
+        ```yaml
+        parameters:
+          customer_name: ${target_name} # Defaults to the target_name
+          kapitan:
+            labels:
+              customer: ${customer_name}
+        ```
+
+    Apply the class to the target for customer `acme`
+    !!! example "`inventory/targets/customers/acme.yml`"
+
+        ```yaml
+        classes:
+        ...
+        - type.customer_project
+
+        parameters:
+        ...
+        ```
+
+    You can now selectively compile targets for customer `acme` using the following (see see [**Labels**](../commands/kapitan_compile.md#using-labels) for more details )
+
+    !!! example ""
+
+        ```shell
+        kapitan compile -l customer=acme
+        Compiled acme (0.06s)
+        Compiled acme-documentation (0.09s)
+        ```
+
+## Topics
+
+Topics let targets expose a subset of their parameters so that other targets can
+aggregate and consume them, without resorting to backend-specific features like
+reclass exports or expensive `inventory_global()` scans.
+
+A target opts into a topic by declaring parameters under
+`parameters.kapitan.topics.<topic_name>.parameters`:
+
+!!! example "`inventory/targets/target-1.yml`"
+    ```yaml
+    parameters:
+      colour: red
+      kapitan:
+        topics:
+          colours:
+            parameters:
+              colour: ${colour}
+    ```
+
+!!! example "`inventory/targets/target-2.yml`"
+    ```yaml
+    parameters:
+      colour: blue
+      kapitan:
+        topics:
+          colours:
+            parameters:
+              colour: ${colour}
+    ```
+
+Kapitan aggregates participating targets into a single topic view of the shape
+`{parameters: {targets: {<target_name>: <topic_parameters>}}}`. The `topics()`
+function is available to every input type (kadet, jinja2, jsonnet). Call it
+without arguments to get the full mapping of all topics, or with a name to get
+a single topic.
+
+!!! example "kadet (`components/painter/__init__.py`)"
+    ```python
+    from kapitan.inputs.kadet import topics
+
+    def main():
+        target_colours = {}
+        for target, parameters in topics("colours").parameters.targets.items():
+            target_colours[target] = {"colour": parameters.colour}
+        return target_colours
+    ```
+
+!!! example "jinja2 (`components/painter.j2`)"
+    ```jinja
+    {% for target, parameters in topics("colours").parameters.targets.items() %}
+    {{ target }}:
+      colour: {{ parameters.colour }}
+    {% endfor %}
+    ```
+
+!!! example "jsonnet (`components/painter.jsonnet`)"
+    ```jsonnet
+    local kap = import "lib/kapitan.libjsonnet";
+    {
+      [target]: { colour: params.parameters.colour }
+      for target in std.objectFields(kap.topics("colours").parameters.targets)
+      for params in [kap.topics("colours").parameters.targets[target]]
+    }
+    ```
+
+This compiles into:
+
+```yaml
+target-1:
+  colour: red
+target-2:
+  colour: blue
+```
+
+Topics are inventory-backend agnostic and only collect what each target
+explicitly opts into, avoiding cryptic query expressions and full inventory
+scans.
+
+### Inspecting topics from the CLI
+
+The `inventory` subcommand has a `--topics` flag for inspecting the aggregated
+view without compiling anything.
+
+!!! example "List all topics"
+    ```shell
+    kapitan inventory --topics
+    ```
+
+!!! example "Show a single topic"
+    ```shell
+    kapitan inventory --topics colours
+    ```
+
+`--topics` combines with `--pattern` to drill into the result and with `--flat`
+to produce flat keys:
+
+```shell
+kapitan inventory --topics colours --pattern parameters.targets
+kapitan inventory --topics --flat
+```
+---
+
+## Next steps
+
+- Review the [inventory introduction](introduction.md) for a refresher on targets and classes.
+- Learn about [inventory backends](backends.md) such as reclass-rs and OmegaConf.
+- Explore the [`kapitan compile` CLI reference](../commands/kapitan_compile.md#using-labels) for more label options.

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/cli.py

@@ -414,6 +414,14 @@ def build_parser():
         metavar="INT",
         help="Indentation spaces for inventory output, default is 2",
     )
+    inventory_parser.add_argument(
+        "--topics",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="NAME",
+        help="show aggregated topics instead of target inventory",
+    )
     inventory_parser.add_argument(
         "--multiline-string-style",
         "-L",
@@ -679,8 +687,9 @@ def main(*argv):
         getattr(args, "func", None) == generate_inventory
         and args.pattern
         and args.target_name == ""
+        and getattr(args, "topics", None) is None
     ):
-        parser.error("--pattern requires --target_name")
+        parser.error("--pattern requires --target_name or --topics")
 
     logger.debug("Running with args: %s", args)
 

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/inputs/jinja2.py

@@ -11,6 +11,7 @@ import os
 from kapitan import cached
 from kapitan.inputs.base import CompiledFile, InputType
 from kapitan.inventory.model.input_types import KapitanInputTypeJinja2Config
+from kapitan.topics import topics
 from kapitan.utils import render_jinja2
 
 
@@ -52,6 +53,7 @@ class Jinja2(InputType):
 
         context["inventory_global"] = cached.global_inv
         context["inventory"] = cached.global_inv[target_name]
+        context["topics"] = topics
         context["input_params"] = input_params
         vars = cached.global_inv[target_name]["parameters"]["kapitan"]["vars"]
         context.update(vars)

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/inputs/kadet.py

@@ -46,6 +46,20 @@ def inventory(lazy=False):
     return inventory_global(lazy)[current_target.get()]
 
 
+def topics(name=None, lazy=False):
+    """Kadet-flavoured wrapper around :func:`kapitan.topics.topics`.
+
+    Returns the same data as the core ``topics()`` function but wrapped in a
+    ``kadet.Dict`` to enable attribute-style access::
+
+        for target, params in topics("colours").parameters.targets.items():
+            ...
+    """
+    from kapitan.topics import topics as _topics
+
+    return Dict(_topics(name), default_box=lazy)
+
+
 def inventory_frozen():
     return kadet.Box(data=inventory().dump(), frozen_box=True)
 

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/inventory/inventory.py

@@ -61,6 +61,42 @@ class Inventory(ABC):
             for target in self.targets.values()
         }
 
+    @functools.cached_property
+    def topics(self) -> dict:
+        """
+        Aggregate ``kapitan.topics`` declarations across all targets.
+
+        Returns a mapping ``topic_name -> {"parameters": {"targets": {target_name: parameters}}}``
+        suitable for consumption via the ``topics("<name>")`` helper in kadet
+        components.
+
+        A target opts into a topic by declaring::
+
+            parameters:
+              kapitan:
+                topics:
+                  <topic_name>:
+                    parameters:
+                      <key>: <value>
+
+        Topic parameters from each participating target are collected under
+        ``parameters.targets.<target_name>`` of the resulting topic entry.
+        """
+        topics: dict[str, dict[str, dict]] = {}
+        for target in self.targets.values():
+            target_topics = getattr(target.parameters.kapitan, "topics", None) or {}
+            for topic_name, topic_values in target_topics.items():
+                # support both pydantic model and raw dict
+                topic_params = getattr(topic_values, "parameters", None)
+                if topic_params is None and isinstance(topic_values, dict):
+                    topic_params = topic_values.get("parameters", {})
+                topics.setdefault(topic_name, {})[target.name] = topic_params or {}
+
+        return {
+            name: {"parameters": {"targets": targets}}
+            for name, targets in topics.items()
+        }
+
     def __initialise(self, ignore_class_not_found) -> bool:
         """
         look for targets at '<inventory_path>/targets/' and initialise them.

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/inventory/model/__init__.py

@@ -13,6 +13,11 @@ class KapitanEssentialVars(BaseModel):
 
 
 class KapitanInventorySettings(BaseModel):
+    # ``extra="allow"`` lets targets declare additional kapitan settings (such
+    # as ``topics``) without polluting the dumped inventory with empty default
+    # fields for targets that opt out.
+    model_config = ConfigDict(extra="allow")
+
     compile: list[CompileInputTypeConfig] = []
     vars: KapitanEssentialVars = KapitanEssentialVars()
     labels: dict[str, str] = {}

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/lib/kapitan.libjsonnet

@@ -8,6 +8,7 @@
   dir_files_read(name):: std.native("dir_files_read")(name),
   inventory(target=std.extVar("target"), inv_path=null):: std.native("inventory")(target, inv_path),
   inventory_global(target=null, inv_path=null):: std.native("inventory")(target, inv_path),
+  topics(name=null):: std.native("topics")(name),
   yaml_dump(obj):: std.native("yaml_dump")(std.toString(obj)),
   yaml_dump_stream(obj):: std.native("yaml_dump_stream")(std.toString(obj)),
   sha256(obj):: std.native("sha256_string")(std.toString(obj)),

{kapitan-0.35.2.dev21 → kapitan-0.35.2.dev23}/kapitan/resources.py

@@ -23,6 +23,7 @@ from kapitan import __file__ as kapitan_install_path
 from kapitan import cached
 from kapitan.errors import CompileError, InventoryError
 from kapitan.inventory import Inventory, get_inventory_backend
+from kapitan.topics import topics
 from kapitan.utils import (
     PrettyDumper,
     StrEnum,
@@ -56,6 +57,7 @@ def resource_callbacks(search_paths):
             partial(jinja2_render_file, search_paths),
         ),
         "inventory": (("target", "inv_path"), partial(inventory, search_paths)),
+        "topics": (("name",), topics),
         "file_read": (("name",), partial(read_file, search_paths)),
         "file_exists": (("name",), partial(file_exists, search_paths)),
         "dir_files_list": (("name",), partial(dir_files_list, search_paths)),
@@ -332,7 +334,17 @@ def generate_inventory(args):
     try:
         inv = get_inventory(args.inventory_path)
 
-        if args.target_name:
+        # ``--topics`` is mutually informative with ``--target-name``: if a
+        # topic name is provided we dump that single topic; otherwise we dump
+        # the full topics mapping. Topic data is plain dicts (see
+        # ``kapitan.topics``) so it flows through the existing yaml dumping.
+        topics_arg = getattr(args, "topics", None)
+        if topics_arg is not None:
+            inv = topics(topics_arg) if topics_arg else topics()
+            if args.pattern:
+                pattern = args.pattern.split(".")
+                inv = deep_get(inv, pattern)
+        elif args.target_name:
             inv = inv.inventory[args.target_name]
             if args.pattern:
                 pattern = args.pattern.split(".")

kapitan-0.35.2.dev23/kapitan/topics.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+# Copyright 2026 The Kapitan Authors
+# SPDX-FileCopyrightText: 2024 The Kapitan Authors <kapitan-admins@googlegroups.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Topics: cross-target parameter aggregation.
+
+Targets opt into a topic by declaring parameters under
+``parameters.kapitan.topics.<name>.parameters``. Kapitan aggregates each
+participating target's topic parameters into a single view of shape::
+
+    {"parameters": {"targets": {<target_name>: <topic_parameters>, ...}}}
+
+This module exposes a single :func:`topics` accessor that is independent of any
+particular input type (kadet, jinja2, jsonnet, ...).
+"""
+
+from kapitan import cached
+
+
+# Empty, well-shaped result returned when a requested topic does not exist, so
+# callers can iterate ``.parameters.targets`` safely.
+_EMPTY_TOPIC: dict = {"parameters": {"targets": {}}}
+
+
+def topics(name: str | None = None) -> dict:
+    """Return aggregated topic parameters across all targets.
+
+    Args:
+        name: Topic name. When ``None`` (or empty), returns the full mapping of
+            every topic keyed by topic name. When provided, returns the single
+            topic view, or an empty well-shaped dict if the topic is unknown.
+
+    Returns:
+        Plain ``dict`` data suitable for any input type. Kadet additionally
+        wraps the result in a ``kadet.Dict`` for attribute-style access.
+    """
+    all_topics = getattr(cached.inv, "topics", {}) or {}
+    if not name:
+        return all_topics
+    return all_topics.get(name, dict(_EMPTY_TOPIC))