Kapitan Documentation

Kapitan is designed for complex infrastructure scenarios where:

• You manage the same application across many environments (dev, staging, prod, regions) and need a single source of truth.
• You need to reuse configuration fragments (classes) across different targets without duplication.
• You need to combine multiple templating tools (e.g., Helm, Kustomize, Jsonnet, Jinja2, CUE) in a single pipeline.
• You require native secret management (GPG, Vault, AWS KMS, GCP KMS, Azure Key Vault) embedded directly in your configuration workflow.
• You prefer a GitOps-friendly workflow that generates fully rendered, static output before deployment.

The Compile process transforms your inventory and templates into usable configuration files.

1. Trigger: Run kapitan compile.
2. Execution: Kapitan reads the inventory, processes Input types (like Jsonnet, Jinja2, Helm, or Kustomize), and runs templates.
3. Output: Generated files are written to the compiled/ directory. Each target has its own subdirectory that mirrors its target name.
4. Parallelism: Kapitan compiles targets in parallel. You can control the number of processes using the -p flag.

Kapitan manages sensitive and dynamic values through a system called References (formerly known as Secrets). It supports multiple backends for retrieving these values, including:

• GPG
• AWS KMS
• GCP KMS
• Azure Key Vault
• HashiCorp Vault
• Plain/Base64 (for non-sensitive data)

The bundle mutation allows you to control how generated resources are grouped into files. By default, a generator might bundle everything into one file, but you can use bundle mutations with conditions (based on the resource kind) to split resources into specific files.

Example: Moving all CustomResourceDefinition resources into a dedicated -crds.yml file.

mutations:
  bundle:
    - conditions:
        kind: [CustomResourceDefinition]
      filename: '{content.component_name}-crds'

Kapitan acts as a central engine that takes raw data from an Inventory and produces specific configurations for downstream tools.

The Workflow:

1. Data Source: You define your data (e.g., bucket_name = "my-app-bucket") in the Inventory.
2. Kapitan Engine: Kapitan processes this data using templates.
3. Downstream Outputs:
   • Kubernetes: Generates a ConfigMap using the bucket_name.
   • Terraform: Creates the actual bucket using the bucket_name.
   • Helm: Configures a Helm chart to use the bucket_name.
   • Documentation: References the correct bucket_name in text.
   • Scripts: Provides the bucket_name to automation scripts.

Kapitan is a pre-deployment configuration generator that uses an inventory-driven model to manage Kubernetes manifests across multiple environments. It does not replace kubectl or your cluster, but rather compiles data from a reusable inventory into the final YAML or JSON files required by your deployment tools.

The Workflow:

1. Model your data: Define reusable data in Kapitan inventory files (inventory/classes/ and inventory/targets/).
2. Choose an input type: Select a method for generating manifests (e.g., Jsonnet, Jinja, Kadet, Helm, or Kustomize).
3. Run kapitan compile: Render the final files into the compiled/<target-name>/ directory.
4. Apply the output: Use kubectl apply -f compiled/<target-name>/manifests/ or a GitOps tool (like ArgoCD or Flux) to deploy the manifests to your cluster.

Use Kapitan's References to embed secrets in manifests without exposing plaintext values in your repository. You can use a reference tag like ?{gpg:...} in your inventory parameters.

At compile time, the reference tag is embedded in the manifest. You can later reveal the values using kapitan refs --reveal or use a tool like Tesoro to decrypt them inside the cluster.

Example usage in inventory:

parameters:
  mysql:
    root_password: ?{gpg:targets/${target_name}/mysql/root_password}

Kapitan allows you to access specific keys within a YAML reference using the @ syntax. This is useful for ingesting complex YAML outputs from external tools and picking only the required fields for your inventory parameters.

Syntax: ?{ref_name@path.to.key}

Example: If you have a reference plain:larder containing:

food:
  apples: 1

You can access the value of apples in your inventory using:

parameters:
  number_of_apples: ?{plain:larder@food.apples}

The env backend allows you to reference environment variables at runtime.

For a reference like ?{env:targets/envs_defaults/mysql_port_${target_name}}, Kapitan looks for an environment variable named KAPITAN_VAR_mysql_port_${TARGET_NAME}.

Note: If the environment variable is not found, Kapitan falls back to the default value stored in the file at refs/targets/envs_defaults/mysql_port_${TARGET_NAME}.

kapitan refs --write env:refs/targets/envs_defaults/mysql_port_${TARGET_NAME} -t ${TARGET_NAME} -f <input file>

The Inventory is a hierarchical YAML-based structure used to capture configuration data that is passed to Kapitan's templating engines. It is composed of two main entities: Classes and Targets.

• Classes: Found in inventory/classes/, these define reusable, common settings and data. They are identified by names that map to their directory structure (e.g., kapicorp.common maps to classes/kapicorp/common.yml).
• Targets: Found in inventory/targets/, these represent specific environments or components (e.g., production, staging) that you want to manage. A target file specifies which classes to include and provides its own specific parameters.

# Example Class structure
classes:
  - common

parameters:
  key: value

# Example Target structure
classes:
  - kapicorp.common
  - components.web

parameters:
  target_name: web