# kapicorp/kapitan architecture

> Architecture diagram of the GitHub repository kapicorp/kapitan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kapicorp/kapitan
- Repository: https://github.com/kapicorp/kapitan

## Overview

##### Project Type and Purpose
- Kapitan is an advanced configuration management **CLI tool** written in Python.
- It compiles declarative inventory, templates, and secrets into deployment-ready manifests (YAML, JSON, Terraform, etc.).
- It provides pluggable backends for inventory (Reclass, OmegaConf), input types (jsonnet, jinja2, helm, copy, external), and secret managers (AWS KMS, GCP KMS, Vault, GPG).

##### High‑Level Architecture Components
a. Presentation Layer
- kapitan CLI entrypoint (`bin/kapitan`, `kapitan/__main__.py`)
- Argument parser & command dispatcher (`kapitan/cli.py`)
b. Application Core
- Initialiser (`kapitan/initialiser.py`)
- Inventory loader & model (`kapitan/inventory/*`)
- Input handlers (“compiler adapters”) (`kapitan/inputs/*`)
- Dependency manager (`kapitan/dependency_manager/*`)
- Reference resolvers & secrets (`kapitan/refs/*`)
- Resource library & helpers (`kapitan/lib`, `kapitan/resources.py`)
- Validation & linting (`kapitan/lint.py`, `kapitan/validate`)
c. External Integrations
- Template engines & tools: Jsonnet, Jinja2, Helm, Kadet
- Secret backends: AWS KMS, GCP KMS, Azure Key Vault, Vault KV/transit, GPG
- Inventory backends: Reclass, OmegaConf
- Optional Docker environment (Dockerfile, container image)
d. Output Layer
- Compiled artifacts written to `<target>/compiled` directories
- Exported scripts (e.g., `apply.sh`, `kubectl.sh`) and manifests (YAML/JSON/Terraform)

##### Relationships & Interactions
- User invokes `kapitan <command> --inventory=<inv> --output=<out>`.
→ CLI parses and routes to the Initialiser.
- Initialiser calls the **Inventory Loader**, which:
→ loads inventory files via selected backend (Reclass/OmegaConf).
- The **Compile Engine** orchestrates:
→ Input modules pull in components and templates.
→ Reference resolvers decrypt or fetch secrets.
→ Dependency manager orders component renderings.
→ Each input type invokes external tool or library (e.g., run `jsonnet`, `helm template`, apply Jinja2 filters).
- Outputs are written to the file system under `compiled/` or other target directories.
- Validation & linting modules validate the resulting manifests’ schema, formatting, and policies.

##### Architectural Patterns & Principles
- **Plug‑in/Strategy** pattern for inputs, inventory backends, and secret backends.
- **Layered Architecture** separating CLI, core logic, extension interfaces, and external systems.
- **Single Responsibility** modules (one module per input type, one per secret backend, etc.).
- **Extensibility**: new input types or backends drop in under `kapitan/inputs` or `kapitan/refs/secrets`.

##### Elements
- Arrowheads indicating flow direction.
- Rectangles for internal modules
- Clouds for external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLIEntrypoint["Kapitan CLI Entrypoint"]:::green
        ArgParser["Argument Parser & Command Dispatcher"]:::green
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Initialiser["Initialiser"]:::green
        InventoryLoader["Inventory Loader & Model"]:::green
        CompileEngine["Compile Engine"]:::green
        DependencyManager["Dependency Manager"]:::green
        RefResolver["Reference Resolvers & Secret Manager"]:::green
        ResourceLibrary["Resource Library & Helpers"]:::green
        Validation["Validation & Linting"]:::green
    end

    %% Plugin Interfaces
    subgraph "Plugin Interfaces"
        direction TB
        Inputs["Input Handlers"]:::blue
        InventoryBackends["Inventory Backends"]:::blue
        SecretBackends["Secret Backends"]:::blue
    end

    %% External Tools & Services
    subgraph "External Tools & Services"
        direction TB
        Jsonnet["Jsonnet"]:::orange
        Jinja2["Jinja2"]:::orange
        HelmCLI["Helm CLI"]:::orange
        Kadet["Kadet"]:::orange
        AWSKMS["AWS KMS"]:::orange
        GCPKMS["GCP KMS"]:::orange
        AzureKV["Azure Key Vault"]:::orange
        Vault["Vault KV/Transit"]:::orange
        GPG["GPG"]:::orange
    end

    %% Output Store
    FileSystem["Compiled Output Store"]:::gray

    %% Relationships
    CLIEntrypoint -->|"invokes"| ArgParser
    ArgParser -->|"parses & routes"| Initialiser
    Initialiser -->|"load inventory"| InventoryLoader
    InventoryLoader -->|"uses backend"| InventoryBackends
    Initialiser -->|"starts compile"| CompileEngine
    CompileEngine -->|"render inputs"| Inputs
    CompileEngine -->|"manage deps"| DependencyManager
    CompileEngine -->|"resolve secrets"| RefResolver
    CompileEngine -->|"access resources"| ResourceLibrary
    CompileEngine -->|"validate"| Validation
    CompileEngine -->|"write artifacts"| FileSystem

    Inputs -->|"invoke"| Jsonnet
    Inputs -->|"invoke"| Jinja2
    Inputs -->|"invoke"| HelmCLI
    Inputs -->|"invoke"| Kadet

    RefResolver -->|"decrypt/fetch"| SecretBackends
    InventoryBackends -->|"Reclass/OmegaConf"| InventoryBackends

    SecretBackends -->|"AWS"| AWSKMS
    SecretBackends -->|"GCP"| GCPKMS
    SecretBackends -->|"Azure"| AzureKV
    SecretBackends -->|"Vault"| Vault
    SecretBackends -->|"GPG"| GPG

    %% Click Events
    click CLIEntrypoint "https://github.com/kapicorp/kapitan/tree/master/bin/kapitan"
    click CLIEntrypoint "https://github.com/kapicorp/kapitan/blob/master/kapitan/__main__.py"
    click ArgParser "https://github.com/kapicorp/kapitan/blob/master/kapitan/cli.py"
    click Initialiser "https://github.com/kapicorp/kapitan/blob/master/kapitan/initialiser.py"
    click InventoryLoader "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/inventory.py"
    click InventoryLoader "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/model/__init__.py"
    click InventoryLoader "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/model/dependencies.py"
    click InventoryLoader "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/model/input_types.py"
    click InventoryLoader "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/model/references.py"
    click InventoryBackends "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/backends/omegaconf/__init__.py"
    click InventoryBackends "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/backends/omegaconf/migrate.py"
    click InventoryBackends "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/backends/omegaconf/resolvers.py"
    click InventoryBackends "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/backends/reclass/__init__.py"
    click InventoryBackends "https://github.com/kapicorp/kapitan/blob/master/kapitan/inventory/backends/reclass_rs/__init__.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/base.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/copy.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/external.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/helm.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/jinja2.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/jsonnet.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/kadet.py"
    click Inputs "https://github.com/kapicorp/kapitan/blob/master/kapitan/inputs/remove.py"
    click DependencyManager "https://github.com/kapicorp/kapitan/blob/master/kapitan/dependency_manager/__init__.py"
    click DependencyManager "https://github.com/kapicorp/kapitan/blob/master/kapitan/dependency_manager/base.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/base.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/base64.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/cmd_parser.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/env.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/functions.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/vault_resources.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/secrets/awskms.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/secrets/azkms.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/secrets/gkms.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/secrets/gpg.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/secrets/vaultkv.py"
    click RefResolver "https://github.com/kapicorp/kapitan/blob/master/kapitan/refs/secrets/vaulttransit.py"
    click ResourceLibrary "https://github.com/kapicorp/kapitan/blob/master/kapitan/lib/kapitan.libjsonnet"
    click ResourceLibrary "https://github.com/kapicorp/kapitan/blob/master/kapitan/resources.py"
    click Validation "https://github.com/kapicorp/kapitan/blob/master/kapitan/lint.py"
    click FileSystem "https://github.com/kapicorp/kapitan/tree/master/compiled/"
    click FileSystem "https://github.com/kapicorp/kapitan/tree/master/compiled/<target>/"

    %% Styles
    classDef green fill:#d0f0c0,stroke:#2e7d32,stroke-width:2px;
    classDef blue fill:#bbdefb,stroke:#1565c0,stroke-width:2px;
    classDef orange fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef gray fill:#eeeeee,stroke:#424242,stroke-width:2px;
```
