kapitan 0.35.2.dev12__tar.gz → 0.35.2.dev14__tar.gz

{kapitan-0.35.2.dev12 → kapitan-0.35.2.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.35.2.dev12
+Version: 0.35.2.dev14
 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.dev14/docs/pages/glossary.md

@@ -0,0 +1,137 @@
+---
+title: "Kapitan Glossary"
+description: "Definitions of key terms and concepts used throughout Kapitan documentation and the configuration management workflow."
+---
+
+# Glossary
+
+This page defines the key terms used throughout Kapitan. Use it to quickly look up a concept or to understand how ideas relate to each other.
+
+## Inventory terms
+
+### Inventory
+
+The hierarchical data store that feeds configuration into Kapitan. It is built from classes and targets stored as YAML files under the `inventory/` directory. The inventory is the single source of truth for all parameters that templates consume during compilation.
+
+[Learn more about the inventory](inventory/introduction.md)
+
+### Target
+
+A specific environment or deployment unit that Kapitan compiles. Each target is a YAML file under `inventory/targets/` that lists classes to inherit and defines its own parameters. A target name is derived from its relative path: `inventory/targets/prod.yml` becomes `prod`, and `inventory/targets/teams/devops/grafana.yml` becomes `teams.devops.grafana`.
+
+[Learn more about targets](inventory/targets.md)
+
+### Class
+
+A reusable YAML fragment under `inventory/classes/` that defines shared parameters and can reference other classes. Classes let you compose configuration without copy-paste. A class name is derived from its relative file path, with `init.yml` files mapping to their parent directory name (the reclass convention).
+
+[Learn more about classes](inventory/classes.md)
+
+### Parameters
+
+The `parameters` section in a target or class file. This is where you define the key-value data that templates read during compilation. Parameters can be scalar values, lists, or nested dictionaries.
+
+### Parameter interpolation
+
+The mechanism that lets you reference other parameter values using `${...}` syntax. For example, `${teams.devops.config.region}` resolves to the value defined in another part of the inventory. Different backends support different interpolation features.
+
+[Learn more about parameter interpolation](inventory/parameters_interpolation.md)
+
+### Inventory backend
+
+The engine that parses and merges the inventory. Kapitan supports multiple backends:
+
+- **reclass** — the default Python backend.
+- **reclass-rs** — a faster Rust implementation of reclass.
+- **omegaconf** — an alternative backend with different merging and interpolation behavior.
+
+[Learn more about backends](inventory/backends.md)
+
+## Compilation terms
+
+### Compile
+
+The process of reading the inventory, running input templates, and writing generated files to the `compiled/` directory. You trigger compilation with `kapitan compile`. Each target gets its own subdirectory under `compiled/` that mirrors the target name.
+
+[Learn more about compilation](core_concepts.md)
+
+### Input type
+
+The templating engine or data source that produces output during compilation. Kapitan supports many input types, including Jsonnet, Jinja2, Kadet (Python), Helm, Kustomize, CUE, external commands, copy, and remove. Each input type is configured inside the `kapitan.compile` list of a target.
+
+[Learn more about input types](input_types/introduction.md)
+
+### Compiled output
+
+The directory tree produced by `kapitan compile`, located at `compiled/`. Each target has its own subdirectory containing the generated files. This output is plain text and can be committed to version control, reviewed in pull requests, or fed directly to a deployment pipeline.
+
+### Parallelism
+
+Kapitan compiles targets in parallel using multiple processes. The default parallelism is `min(number_of_targets, cpu_count)`. You can control it with the `-p` flag.
+
+## References and secrets
+
+### Reference
+
+A placeholder for a value that is stored outside the inventory, typically because it is sensitive or highly variable. References use the syntax `?{backend:path}`. During compilation, Kapitan replaces the reference with the actual value. During reveal, encrypted references are decrypted.
+
+[Learn more about references](../references.md)
+
+### Refs directory
+
+The directory where reference files are stored, defaulting to `refs/` in the repository root. Each backend stores its data in a different format within this directory.
+
+### Reveal
+
+The process of decrypting or resolving references so that plain-text values appear in the compiled output. Use `kapitan refs --reveal` to reveal references in existing files.
+
+### Compile-time references
+
+References that are resolved during `kapitan compile`. The compiled output contains the plain value. This requires the appropriate backend credentials or keys to be available at compile time.
+
+## Dependencies
+
+### External dependency
+
+A remote resource that Kapitan fetches before compilation. Supported sources include Git repositories, HTTP(S) URLs, and ORAS (OCI registry) artifacts. Dependencies are declared in `kapitan.dependencies` inside a target.
+
+[Learn more about external dependencies](external_dependencies.md)
+
+### Generator
+
+A reusable template or script that produces Kapitan-compatible output. Generators are often distributed as Git repositories and can be fetched as dependencies. The Kapitan Generators project hosts community generators.
+
+[Learn more about generators](https://generators.kapitan.dev)
+
+## Validation and tooling
+
+### Validate
+
+The process of checking generated output against schemas or rules. Kapitan supports JSON Schema validation, YAML linting, and TOML validation. Validation helps catch configuration errors before deployment.
+
+### Searchvar
+
+A Kapitan subcommand that searches the inventory for parameter values. It is useful for finding where a specific value is defined or used across targets.
+
+### Lint
+
+Static analysis of Kapitan configuration files. The `kapitan lint` command checks for common issues in inventory files, templates, and compiled output.
+
+## GitOps and deployment
+
+### GitOps
+
+An operational model where the desired state of infrastructure is stored in Git and an automated process applies changes. Kapitan fits into GitOps workflows because it compiles plain-text, reviewable configuration that can be committed and deployed by a CD controller.
+
+### Compiled manifest
+
+A generated configuration file ready for deployment. In a Kubernetes context, this is typically a YAML manifest. In a Terraform context, this is a `.tf` file or a Terraform plan. Kapitan itself does not deploy; it generates the artifacts that a deployment tool consumes.
+
+## See also
+
+- [Core Concepts](core_concepts.md)
+- [Inventory Introduction](inventory/introduction.md)
+- [Input Types Introduction](input_types/introduction.md)
+- [References](../references.md)
+- [FAQ](../FAQ.md)
+- [Support](../support.md)

kapitan-0.35.2.dev14/docs/pages/troubleshooting.md

@@ -0,0 +1,195 @@
+---
+title: "Kapitan Troubleshooting"
+description: "Common Kapitan errors and how to resolve them. Covers inventory, compilation, input types, references, and installation issues."
+---
+
+# :kapitan-logo: **Troubleshooting**
+
+This page lists common errors and their resolutions. If your error is not here, try the [`#kapitan`](https://kubernetes.slack.com/archives/C981W2HD3) Slack channel or [GitHub Discussions](https://github.com/kapicorp/kapitan/discussions).
+
+## Installation and environment
+
+### Python version errors
+
+**Symptom:** `kapitan` fails to install or run with syntax or import errors.
+
+Kapitan requires **Python 3.10 or newer**. Check your version:
+
+```shell
+python3 --version
+```
+
+If you are using an older Python, upgrade or use the Docker image instead.
+
+### Docker permission issues
+
+**Symptom:** Files created by the Docker container are owned by root.
+
+On Linux, add `-u $(id -u)` to your `docker run` command:
+
+```shell
+docker run -t --rm -u $(id -u) -v $(pwd):/src:delegated kapicorp/kapitan compile
+```
+
+## Inventory errors
+
+### `No inventory targets discovered at path: ...`
+
+**Cause:** The inventory path does not exist or does not contain any targets.
+
+**Resolution:**
+
+- Ensure you are running `kapitan compile` from the repository root.
+- Verify that `inventory/targets/` exists and contains at least one `.yml` or `.yaml` file.
+- If your inventory is in a non-default location, pass `--inventory-path`:
+
+```shell
+kapitan compile --inventory-path ./my-inventory
+```
+
+### `Error: no targets found`
+
+**Cause:** You used `-t` or `--target` with a name that does not exist.
+
+**Resolution:**
+
+- List available targets with:
+
+```shell
+kapitan inventory --list-targets
+```
+
+- Target names reflect the directory structure under `inventory/targets/`. A file at `inventory/targets/teams/devops/grafana.yml` becomes `teams.devops.grafana`.
+
+### `InventoryError: <target_name>: parameters is empty`
+
+**Cause:** The target file exists but has no `parameters` section.
+
+**Resolution:** Add a `parameters` block to the target, even if minimal:
+
+```yaml
+parameters:
+  kapitan:
+    vars:
+      target: my-target
+```
+
+### `InventoryError: <target_name>: parameters.kapitan has no assignment`
+
+**Cause:** The target is missing the `parameters.kapitan` structure that defines compile inputs.
+
+**Resolution:** Ensure the target has a `kapitan` section with at least an empty `compile` list if there are no inputs:
+
+```yaml
+parameters:
+  kapitan:
+    compile: []
+```
+
+### `Class <class_name> not found`
+
+**Cause:** A target or class references a class that does not exist in the inventory.
+
+**Resolution:**
+
+- Verify the class file exists under `inventory/classes/`.
+- Check that the class name matches the relative path. For example, `inventory/classes/common.yml` is `common`, and `inventory/classes/teams/app.yml` is `teams.app`.
+- Ensure there are no typos in the `classes:` list.
+- If you use `--enable-class-wildcards`, verify that the pattern actually matches existing files.
+
+## Compilation errors
+
+### `CompileError: Error compiling targets: ...`
+
+**Cause:** A compilation step failed. The underlying error is usually printed above this line.
+
+**Resolution:**
+
+- Run with `--verbose` to see the full traceback.
+- Check that all `input_paths` exist and point to the correct files.
+- Verify that template syntax is valid for the input type you are using.
+
+### `InventoryError` during compilation
+
+**Cause:** The inventory backend encountered an error while rendering.
+
+**Resolution:**
+
+- If you are using **reclass**, check for circular class references and invalid `${...}` interpolation syntax.
+- If you are using **omegaconf**, verify that all YAML files are well-formed and that custom resolvers are registered correctly.
+- If you are using **reclass-rs**, ensure the Rust binary is installed and compatible with your inventory.
+
+## Input type errors
+
+### Helm: `helm template` fails or chart not found
+
+**Cause:** The Helm input type cannot locate the chart or Helm values are invalid.
+
+**Resolution:**
+
+- Verify that `input_paths` points to a valid Helm chart directory.
+- If you fetch charts with the dependency manager, run `kapitan compile --fetch` first.
+- Ensure `helm_values` matches the chart's values schema.
+
+### Kustomize: `input_paths` not found
+
+**Cause:** The Kustomize overlay or base directory is missing.
+
+**Resolution:**
+
+- Verify the path exists relative to the repository root.
+- Ensure the directory contains a `kustomization.yaml`.
+
+### Jsonnet: `RUNTIME ERROR` or `failed to compile`
+
+**Cause:** The Jsonnet file has a syntax error, a missing import, or an assertion failure.
+
+**Resolution:**
+
+- Run with `--verbose` to see the exact line number.
+- Verify that `lib/kapitan.libjsonnet` is available if you import it.
+- Check assertion messages for hints about which inventory value is invalid.
+
+## References and secrets
+
+### `?{gpg:...}` or `?{vault:...}` not revealed
+
+**Cause:** The reference exists in the inventory but the secret file is missing from the `refs/` directory.
+
+**Resolution:**
+
+- Ensure the secret was created with `kapitan refs --write ...`.
+- Verify that the `refs/` path is correct.
+- For GPG, ensure your key is in the keychain and the `GPG_HOME` environment is set if needed.
+
+### `RefError` or `KeyError` for references
+
+**Cause:** A reference tag is malformed or the backend is not configured.
+
+**Resolution:**
+
+- Check the reference syntax: `?{backend:path}`.
+- Supported backends: `gpg`, `vault`, `awskms`, `gkms`, `azkv`.
+- Ensure the corresponding backend dependencies and credentials are available.
+
+## Performance
+
+### Compilation is slow
+
+**Cause:** Large inventories, many targets, or slow input types.
+
+**Resolution:**
+
+- Compile only the target you need: `kapitan compile -t <target>`.
+- Increase parallelism with `-p` (defaults to CPU count).
+- Consider switching to the **reclass-rs** backend for faster inventory rendering.
+- If using OmegaConf, check for expensive custom resolvers.
+
+## Next steps
+
+If these resolutions do not solve your problem:
+
+- [Read the core concepts](core_concepts.md) to verify your inventory structure.
+- [Browse the FAQ](../FAQ.md) for additional questions.
+- [Join `#kapitan` on Slack](https://kubernetes.slack.com/archives/C981W2HD3) and search prior discussions.
+- [Open a GitHub Discussion](https://github.com/kapicorp/kapitan/discussions) with the error output and your inventory layout.

{kapitan-0.35.2.dev12 → kapitan-0.35.2.dev14}/mkdocs.yml

@@ -77,6 +77,7 @@ nav:
   - Getting started: getting_started.md
   - Documentation:
       - Core Concepts: pages/core_concepts.md
+      - Glossary: pages/glossary.md
       - Inventory:
         - Introduction: pages/inventory/introduction.md
         - Targets: pages/inventory/targets.md
@@ -114,6 +115,7 @@ nav:
     - pages/blog/index.md
   - Support:
       - Ask for support: support.md
+      - Troubleshooting: pages/troubleshooting.md
       - Related Projects: related.md
   - Contribute:
       - Sponsor Us: pages/contribute/sponsor.md