kapitan 0.35.2.dev17__tar.gz → 0.35.2.dev18__tar.gz

{kapitan-0.35.2.dev17 → kapitan-0.35.2.dev18}/PKG-INFO

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

@@ -0,0 +1,216 @@
+---
+title: "Kapitan Examples: Kubernetes, Terraform, and Infrastructure"
+description: "Explore curated Kapitan examples for Kubernetes, Terraform, and multi-environment infrastructure. Clone the reference repository and compile working targets in minutes."
+---
+
+# :kapitan-logo: **Kapitan Examples**
+
+The fastest way to understand Kapitan is to see it in action. This page collects official examples, reference repositories, and small tutorials you can run locally.
+
+## Reference repository
+
+The [kapicorp/kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository is the best place to start. It contains working examples for Kubernetes, Terraform, and mixed infrastructure setups.
+
+```shell
+git clone git@github.com:kapicorp/kapitan-reference.git kapitan-templates
+cd kapitan-templates
+
+./kapitan compile
+```
+
+Expected output:
+
+```
+Compiled postgres-proxy (1.51s)
+Compiled tesoro (1.70s)
+Compiled echo-server (1.64s)
+Compiled mysql (1.67s)
+Compiled gke-pvm-killer (1.17s)
+Compiled prod-sockshop (4.74s)
+Compiled dev-sockshop (4.74s)
+Compiled tutorial (1.68s)
+Compiled global (0.76s)
+Compiled examples (2.60s)
+Compiled pritunl (2.03s)
+Compiled sock-shop (4.36s)
+```
+
+The repository includes:
+
+- **Kubernetes manifests** generated with Jsonnet and Kadet
+- **Terraform resources** for GCP and AWS
+- **Helm chart rendering** with inventory-driven values
+- **Secrets management** with Kapitan References
+- **Multi-environment setups** (development, staging, production)
+
+## Minimal starter project
+
+If you want a clean slate instead of a full reference repository, use the cookiecutter template:
+
+```shell
+pip3 install cruft
+cruft create http://github.com/kapicorp/kapitan-reference --checkout cookiecutter --no-input
+```
+
+This creates a minimal Kapitan project with:
+
+- A basic inventory structure (`inventory/classes/`, `inventory/targets/`)
+- A pre-configured `kapitan` wrapper script
+- A small working target you can compile immediately
+
+## Input type examples
+
+### Jsonnet
+
+Generate Kubernetes manifests with Jsonnet and access the Kapitan inventory:
+
+```jsonnet
+local kap = import "lib/kapitan.libjsonnet";
+local inv = kap.inventory();
+local p = inv.parameters;
+
+{
+    "deployment": {
+        apiVersion: "apps/v1",
+        kind: "Deployment",
+        metadata: {
+            name: p.target_name,
+            namespace: p.namespace,
+        },
+        spec: {
+            replicas: p.nginx.replicas,
+            template: {
+                spec: {
+                    containers: [{
+                        name: "nginx",
+                        image: p.nginx.image,
+                    }],
+                },
+            },
+        },
+    },
+}
+```
+
+See the full [Jsonnet input type documentation](input_types/jsonnet.md).
+
+### Jinja
+
+Write plain YAML templates with Jinja2 loops and conditionals:
+
+```yaml
+# templates/configmap.yml.j2
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ inventory.parameters.target_name }}
+data:
+  environment: {{ inventory.parameters.environment }}
+```
+
+See the full [Jinja input type documentation](input_types/jinja.md).
+
+### Helm
+
+Render an existing Helm chart with values from the Kapitan inventory:
+
+```yaml
+parameters:
+  kapitan:
+    compile:
+      - output_path: .
+        input_type: helm
+        input_paths:
+          - components/charts/nginx-ingress
+        helm_values:
+          controller:
+            name: my-controller
+        helm_params:
+          name: my-release
+          namespace: my-namespace
+```
+
+See the full [Helm input type documentation](input_types/helm.md).
+
+### Kustomize
+
+Apply Kustomize patches to base manifests generated by another input type:
+
+```yaml
+parameters:
+  kapitan:
+    compile:
+      - output_path: manifests
+        input_type: kustomize
+        input_paths:
+          - components/kustomize/overlays/production
+```
+
+See the full [Kustomize input type documentation](input_types/kustomize.md).
+
+## Inventory examples
+
+### Targets and classes
+
+```yaml
+# inventory/classes/common.yml
+parameters:
+  organization: ACME
+  timezone: Europe/London
+```
+
+```yaml
+# inventory/classes/environments/production.yml
+classes:
+  - common
+
+parameters:
+  environment: production
+  nginx:
+    replicas: 5
+```
+
+```yaml
+# inventory/targets/production/web.yml
+classes:
+  - environments.production
+  - components.nginx
+
+parameters:
+  target_name: web
+```
+
+See the [inventory introduction](inventory/introduction.md) for the full concept.
+
+## Secrets examples
+
+Create an encrypted reference with GPG:
+
+```shell
+kapitan refs --write gpg:targets/production/web/mysql/root_password -t production/web -f secret.txt
+```
+
+Use it in the inventory:
+
+```yaml
+parameters:
+  mysql:
+    root_password: ?{gpg:targets/production/web/mysql/root_password}
+```
+
+See the [References documentation](../references.md) for all backends.
+
+## Related projects
+
+- [Tesoro](https://github.com/kapicorp/tesoro) — Kubernetes Admission Controller for Kapitan secrets
+- [Kapitan Reference](https://github.com/kapicorp/kapitan-reference) — working examples and starter templates
+- [Kapitan Generators](https://generators.kapitan.dev) — reusable generators for Kubernetes and Terraform
+
+---
+
+## Next steps
+
+- [Get started with Kapitan](../getting_started.md)
+- Learn [Kapitan core concepts](core_concepts.md)
+- Understand the [Kapitan inventory](inventory/introduction.md)
+- Compare [Kapitan vs Helm vs Kustomize](kapitan_vs_helm_kustomize.md)

kapitan-0.35.2.dev18/docs/pages/kapitan_vs_helm_kustomize.md

@@ -0,0 +1,134 @@
+---
+title: "Kapitan vs Helm vs Kustomize: When to Use Each Tool"
+description: "Compare Kapitan, Helm, and Kustomize for Kubernetes configuration management. Learn the tradeoffs, when each tool shines, and how they can work together."
+---
+
+# :kapitan-logo: **Kapitan vs Helm vs Kustomize**
+
+Kapitan, Helm, and Kustomize all help you manage Kubernetes configuration, but they solve different problems at different layers. Choosing the right tool—or combining them—depends on your team's size, the complexity of your environments, and how much reuse you need across infrastructure systems.
+
+## Quick comparison
+
+| | **Helm** | **Kustomize** | **Kapitan** |
+|---|---|---|---|
+| **Primary goal** | Package and distribute Kubernetes applications | Patch and customize existing manifests | Generate and organize configuration across environments and tools |
+| **Templating** | Go templates (`values.yaml`) | None (pure YAML overlays) | Jsonnet, Jinja2, Kadet, Helm, Kustomize, CUE |
+| **Reuse across environments** | One chart, many `values.yaml` files | Bases and overlays per environment | Hierarchical inventory with classes and targets |
+| **Multi-tool workflows** | Kubernetes only | Kubernetes only | Kubernetes, Terraform, scripts, docs, secrets |
+| **Secrets management** | External tools (Sealed Secrets, Vault Agent, etc.) | External tools | Built-in references (GPG, KMS, Vault) |
+| **Best for** | Distributing reusable charts | Overlaying environment-specific patches | Complex, multi-environment, multi-tool configuration |
+
+## When to use Helm
+
+Helm is the Kubernetes package manager. It is the best choice when:
+
+- You want to install third-party software on your cluster (for example, Prometheus, nginx-ingress, cert-manager).
+- You are building a reusable application chart that other teams will install with different `values.yaml` files.
+- You need versioning and rollback for releases.
+
+Helm's strength is packaging. Its weakness is that every environment needs its own `values.yaml` file, and values are not easily shared with non-Helm tools. If you have fifty microservices and each needs a slightly different Helm values file, you can end up with a lot of similar YAML that is hard to keep consistent.
+
+Kapitan can help here: you can [render Helm charts inside Kapitan](input_types/helm.md) using the Helm input type, drive the values from the Kapitan inventory, and keep the chart configuration alongside your other infrastructure configuration.
+
+## When to use Kustomize
+
+Kustomize is built into `kubectl` and is the best choice when:
+
+- You already have plain Kubernetes YAML manifests that you want to customize per environment.
+- You prefer patch-based customization over templating.
+- You want a tool that is simple, Kubernetes-native, and does not introduce a new language.
+
+Kustomize's strength is simplicity. Its weakness is that it only works with existing YAML files, and it does not help you generate configuration from scratch or share data with Terraform, scripts, or documentation. As your environments grow, the number of overlays and patches can become difficult to manage.
+
+Kapitan can help here: you can [use Kustomize as an input type](input_types/kustomize.md) to apply patches to manifests generated by other Kapitan input types, or you can generate the base manifests with Jsonnet or Kadet and then patch them with Kustomize.
+
+## When to use Kapitan
+
+Kapitan is a configuration management framework. It is the best choice when:
+
+- You manage Kubernetes manifests, Terraform resources, scripts, and documentation in the same repository.
+- You need a single source of truth for values that are reused across Helm charts, Kustomize overlays, Jsonnet templates, and Terraform modules.
+- You want built-in secrets management that works with GPG, AWS KMS, GCP KMS, Azure Key Vault, or HashiCorp Vault.
+- You have many environments (development, staging, production, multiple regions) and want to model them with a hierarchical inventory instead of many similar values files.
+
+Kapitan does not replace Helm or Kustomize. It integrates with both. You can use Kapitan to:
+
+- Generate Helm `values.yaml` files from the inventory and then render the chart with the Helm input type.
+- Generate base Kubernetes manifests with Jsonnet and patch them with Kustomize.
+- Keep your `bucket_name`, `namespace`, and `replica_count` in one place and use them in Kubernetes ConfigMaps, Terraform resources, and Helm values at the same time.
+
+## Common patterns
+
+### Helm inside Kapitan
+
+Use the [Helm input type](input_types/helm.md) to render an upstream chart while overriding values from the Kapitan inventory:
+
+```yaml
+parameters:
+  kapitan:
+    compile:
+      - output_path: .
+        input_type: helm
+        input_paths:
+          - components/charts/nginx-ingress
+        helm_values:
+          controller:
+            name: my-controller
+        helm_params:
+          name: my-release
+          namespace: my-namespace
+```
+
+### Kustomize inside Kapitan
+
+Use the [Kustomize input type](input_types/kustomize.md) to apply patches to manifests generated by another Kapitan input type:
+
+```yaml
+parameters:
+  kapitan:
+    compile:
+      - output_path: manifests
+        input_type: kustomize
+        input_paths:
+          - components/kustomize/overlays/production
+```
+
+### Plain YAML vs Kapitan inventory
+
+Without Kapitan, you might copy `namespace: production` into every Helm values file, Kustomize overlay, and Terraform variable file. With Kapitan, you define it once in an inventory class and reference it everywhere:
+
+```yaml
+# inventory/classes/environments/production.yml
+parameters:
+  environment: production
+  namespace: production
+```
+
+```yaml
+# inventory/targets/web.yml
+classes:
+  - environments.production
+  - components.web
+
+parameters:
+  kapitan:
+    compile:
+      - output_path: manifests
+        input_type: jinja2
+        input_paths:
+          - templates/deployment.yml.j2
+```
+
+## Summary
+
+- Use **Helm** for packaging and distributing Kubernetes applications.
+- Use **Kustomize** for patching existing manifests per environment.
+- Use **Kapitan** when you need a unified inventory that drives Helm, Kustomize, Jsonnet, Terraform, and secrets together.
+
+---
+
+## Next steps
+
+- Learn how [Kapitan inventory](inventory/introduction.md) models environments with targets and classes.
+- Explore [Kapitan input types](input_types/introduction.md): [Jsonnet](input_types/jsonnet.md), [Jinja](input_types/jinja.md), [Kadet](input_types/kadet.md), [Helm](input_types/helm.md), and [Kustomize](input_types/kustomize.md).
+- See [Kapitan examples](kapitan_examples.md) for real-world setups.

kapitan-0.35.2.dev18/docs/pages/kubernetes_configuration_management.md

@@ -0,0 +1,170 @@
+---
+title: "Kubernetes Configuration Management with Kapitan"
+description: "Learn how Kapitan helps you manage Kubernetes manifests across environments. Compare plain YAML, Helm, Kustomize, and Kapitan workflows with a practical example."
+---
+
+# :kapitan-logo: **Kubernetes Configuration Management with Kapitan**
+
+Managing Kubernetes YAML across development, staging, and production is one of the most common reasons teams adopt Kapitan. This page explains how Kapitan helps you generate, organize, and validate Kubernetes configuration while avoiding duplication and drift.
+
+## The problem
+
+As your infrastructure grows, you typically face one or more of these issues:
+
+- **Duplication:** the same `namespace`, `replicas`, or `image` is copy-pasted across dozens of files.
+- **Drift:** a value changes in one place but not in another, causing environment inconsistencies.
+- **Secrets sprawl:** sensitive values are hardcoded in YAML, scattered across repositories, or managed with ad-hoc scripts.
+- **Tool fragmentation:** Helm values, Kustomize overlays, Terraform variables, and documentation all contain overlapping data that is never in sync.
+
+Kapitan addresses these problems with an [inventory-driven model](inventory/introduction.md): you define data once in reusable [classes](inventory/classes.md), assign them to [targets](inventory/targets.md) (environments or services), and let Kapitan compile that data into the files each tool expects.
+
+## How Kapitan manages Kubernetes configuration
+
+Kapitan does not replace Kubernetes, kubectl, or your cluster. It is a pre-deployment configuration generator. The workflow looks like this:
+
+1. **Model your data** in the Kapitan inventory (`inventory/classes/` and `inventory/targets/`).
+2. **Choose an input type** for generating manifests: [Jsonnet](input_types/jsonnet.md), [Jinja](input_types/jinja.md), [Kadet](input_types/kadet.md), [Helm](input_types/helm.md), or [Kustomize](input_types/kustomize.md).
+3. **Run `kapitan compile`** to render the final YAML or JSON files into `compiled/<target-name>/`.
+4. **Apply the output** to your cluster with `kubectl apply -f compiled/<target-name>/manifests/` or via a GitOps pipeline.
+
+Because the inventory is plain YAML, it is easy to read, diff, and review in pull requests. Because compilation is deterministic, you can validate the output before it ever reaches a cluster.
+
+## Example: deploying an nginx service across environments
+
+### Without Kapitan
+
+You might have:
+
+```
+helm/values-dev.yaml
+helm/values-staging.yaml
+helm/values-prod.yaml
+kustomize/overlays/dev/patch.yaml
+kustomize/overlays/staging/patch.yaml
+kustomize/overlays/prod/patch.yaml
+terraform/variables.tf
+```
+
+Every time you change the `image` tag or `replicas` count, you must update multiple files. If you forget one, environments drift.
+
+### With Kapitan
+
+You define the common data once:
+
+```yaml
+# inventory/classes/components/nginx.yml
+parameters:
+  nginx:
+    image: nginx:1.25
+    replicas: 2
+    ports:
+      - 80
+```
+
+You override per environment:
+
+```yaml
+# inventory/classes/environments/production.yml
+parameters:
+  nginx:
+    replicas: 5
+```
+
+You define the target:
+
+```yaml
+# inventory/targets/production/web.yml
+classes:
+  - components.nginx
+  - environments.production
+
+parameters:
+  kapitan:
+    compile:
+      - output_path: manifests
+        input_type: jinja2
+        input_paths:
+          - templates/nginx-deployment.yml.j2
+```
+
+The Jinja template can use the inventory directly:
+
+```yaml
+# templates/nginx-deployment.yml.j2
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+  namespace: {{ inventory.parameters.target_name }}
+spec:
+  replicas: {{ inventory.parameters.nginx.replicas }}
+  template:
+    spec:
+      containers:
+        - name: nginx
+          image: {{ inventory.parameters.nginx.image }}
+          ports:
+            {% for port in inventory.parameters.nginx.ports %}
+            - containerPort: {{ port }}
+            {% endfor %}
+```
+
+Running `kapitan compile -t production.web` produces:
+
+```
+compiled/production/web/manifests/nginx-deployment.yml
+```
+
+The `replicas` value is `5` because the production class overrides the component default. The `image` value is inherited from the component class. There is no duplication, and the entire configuration state is visible in one PR.
+
+## Choosing an input type for Kubernetes
+
+| Input type | Best for | Kubernetes workflow |
+|---|---|---|
+| [Jsonnet](input_types/jsonnet.md) | Structured manifests, libraries, validation | Write reusable Jsonnet libraries that output Deployment, Service, and ConfigMap objects |
+| [Jinja](input_types/jinja.md) | Simple templates, documentation, scripts | Write plain YAML templates with loops and conditionals |
+| [Kadet](input_types/kadet.md) | Python-based generation, complex logic | Build Kubernetes resources as Python classes and reuse them across components |
+| [Helm](input_types/helm.md) | Existing Helm charts | Render upstream charts with values driven from the Kapitan inventory |
+| [Kustomize](input_types/kustomize.md) | Patching base manifests | Apply environment-specific patches to manifests generated by another input type |
+
+Many teams use more than one input type in the same project. For example, you might generate base manifests with Kadet and then patch them with Kustomize for environment-specific labels.
+
+## Secrets in Kubernetes manifests
+
+Kapitan's [References](../references.md) let you embed secrets in manifests without exposing plaintext values in the repository.
+
+```yaml
+parameters:
+  mysql:
+    root_password: ?{gpg:targets/${target_name}/mysql/root_password}
+```
+
+At compile time, the reference tag is embedded in the manifest. You can reveal it later with `kapitan refs --reveal` or use a tool like [Tesoro](https://github.com/kapicorp/tesoro) to decrypt it inside the cluster.
+
+## Validation
+
+You can validate generated manifests before applying them:
+
+- Use the [`kapitan validate`](commands/kapitan_validate.md) command with JSON Schema.
+- Use the `jsonschema()` function in [Jsonnet](input_types/jsonnet.md) to validate inventory structures at compile time.
+- Pipe compiled output to `kubeval` or `kubectl apply --dry-run=client` in CI.
+
+## GitOps integration
+
+Kapitan fits naturally into GitOps workflows:
+
+1. Engineers change inventory classes or templates in a pull request.
+2. CI runs `kapitan compile` and validates the output.
+3. The compiled directory is committed (or rendered on-the-fly by the CD pipeline).
+4. ArgoCD, Flux, or a custom controller applies the compiled manifests to the cluster.
+
+Because the inventory is declarative YAML, changes are easy to review. Because compilation is reproducible, the CD pipeline can trust the output.
+
+---
+
+## Next steps
+
+- Learn how [Kapitan inventory](inventory/introduction.md) works with [targets](inventory/targets.md) and [classes](inventory/classes.md).
+- Explore the [Kapitan vs Helm vs Kustomize](kapitan_vs_helm_kustomize.md) comparison.
+- Try the [Kapitan examples](kapitan_examples.md) or clone the [kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository.
+- Set up [References](../references.md) for managing secrets in your Kubernetes configuration.

{kapitan-0.35.2.dev17 → kapitan-0.35.2.dev18}/mkdocs.yml

@@ -77,6 +77,9 @@ nav:
   - Getting started: getting_started.md
   - Documentation:
       - Core Concepts: pages/core_concepts.md
+      - Kubernetes Configuration Management: pages/kubernetes_configuration_management.md
+      - Kapitan vs Helm vs Kustomize: pages/kapitan_vs_helm_kustomize.md
+      - Examples: pages/kapitan_examples.md
       - Glossary: pages/glossary.md
       - Inventory:
         - Introduction: pages/inventory/introduction.md