Skip to content

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 repository is the best place to start. It contains working examples for Kubernetes, Terraform, and mixed infrastructure setups.

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:

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:

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.

Jinja

Write plain YAML templates with Jinja2 loops and conditionals:

# 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.

Helm

Render an existing Helm chart with values from the Kapitan inventory:

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.

Kustomize

Apply Kustomize patches to base manifests generated by another input type:

parameters:
  kapitan:
    compile:
      - output_path: manifests
        input_type: kustomize
        input_paths:
          - components/kustomize/overlays/production

See the full Kustomize input type documentation.

Inventory examples

Targets and classes

# inventory/classes/common.yml
parameters:
  organization: ACME
  timezone: Europe/London

# inventory/classes/environments/production.yml
classes:
  - common

parameters:
  environment: production
  nginx:
    replicas: 5

# inventory/targets/production/web.yml
classes:
  - environments.production
  - components.nginx

parameters:
  target_name: web

See the inventory introduction for the full concept.

Secrets examples

Create an encrypted reference with GPG:

kapitan refs --write gpg:targets/production/web/mysql/root_password -t production/web -f secret.txt

Use it in the inventory:

parameters:
  mysql:
    root_password: ?{gpg:targets/production/web/mysql/root_password}

See the References documentation for all backends.

Next steps