Kustodian

A GitOps templating framework for Kubernetes with Flux CD. Define templates in YAML, bootstrap clusters, and extend with plugins.

What is Kustodian?

Kustodian is a framework for managing Kubernetes cluster configurations using a declarative, YAML-based approach. It generates Flux CD Kustomizations from simple template definitions, making it easy to:

• Define reusable templates for Kubernetes applications
• Bootstrap clusters with k0s, Talos, or other providers
• Manage nodes with declarative labeling and configuration
• Manage multiple clusters with shared or unique configurations
• Extend functionality through a plugin system
• Keep everything in YAML - no TypeScript or code required

Why Kustodian?

Managing Kubernetes configurations at scale is hard. You end up with:

• Duplicated YAML across clusters
• Complex Kustomize overlays that are hard to reason about
• Manual cluster provisioning with ad-hoc scripts
• Inconsistent node labeling across environments
• Custom scripts to generate configurations
• No standard way to handle secrets, auth providers, or monitoring

Kustodian solves this by providing:

| Problem | Kustodian Solution | |---------|-------------------| | Duplicated configs | Reusable templates with substitutions | | Complex overlays | Simple YAML template definitions | | Manual provisioning | Declarative cluster bootstrap with k0s/Talos | | Inconsistent nodes | YAML-based node definitions with auto-labeling | | Custom scripts | Standardized generation engine | | No extensibility | Plugin system for secrets, auth, etc. |

Quick Example

Define a Template

# templates/nginx/template.yaml
apiVersion: kustodian.io/v1
kind: Template
metadata:
  name: nginx
spec:
  kustomizations:
    - name: deployment
      path: ./deployment
      namespace:
        default: nginx
      substitutions:
        - name: replicas
          default: "2"
        - name: image_tag
          default: "latest"
      health_checks:
        - kind: Deployment
          name: nginx

Configure a Cluster

# clusters/production/cluster.yaml
apiVersion: kustodian.io/v1
kind: Cluster
metadata:
  name: production
spec:
  domain: example.com

  git:
    owner: myorg
    repository: infrastructure
    branch: main
    path: clusters/production

  templates:
    - name: nginx
      enabled: true
      values:
        replicas: "5"
        image_tag: "1.25"

Define Nodes

# clusters/production/nodes.yaml
apiVersion: kustodian.io/v1
kind: NodeList
metadata:
  cluster: production
spec:
  label_prefix: myorg.io
  ssh:
    user: admin
    key_path: ~/.ssh/cluster_key
  nodes:
    - name: node-1
      role: controller+worker
      address: 10.0.0.11
      labels:
        metallb: true
        storage: nvme

    - name: node-2
      role: worker
      address: 10.0.0.12
      labels:
        gpu: nvidia

Apply Configuration

# Apply full cluster configuration (bootstrap + Flux + templates)
kustodian apply --cluster production

This bootstraps the cluster, installs Flux CD, and deploys your templates.

Core Concepts

Templates

Templates define reusable Kubernetes configurations. Each template contains one or more kustomizations - units of deployment that map to Flux Kustomization resources.

apiVersion: kustodian.io/v1
kind: Template
metadata:
  name: my-app
spec:
  kustomizations:
    - name: operator      # Deployed first
      path: ./operator
      namespace:
        default: my-app

    - name: instance      # Deployed after operator
      path: ./instance
      depends_on:
        - operator

Clusters

Clusters define where and how templates are deployed. Each cluster specifies which templates to enable and what values to use.

apiVersion: kustodian.io/v1
kind: Cluster
metadata:
  name: staging
spec:
  domain: staging.example.com
  templates:
    - name: my-app
      enabled: true
      values:
        replicas: "1"

Nodes

Nodes define the physical or virtual machines in your cluster. Kustodian manages node configuration, labeling, and can bootstrap entire clusters.

apiVersion: kustodian.io/v1
kind: NodeList
metadata:
  cluster: staging
spec:
  label_prefix: myorg.io          # Labels will be myorg.io/metallb, etc.
  ssh:
    user: admin
    key_path: ~/.ssh/cluster_key
  nodes:
    - name: control-1
      role: controller+worker     # Runs control plane + workloads
      address: 10.0.0.10
      labels:
        metallb: true             # Applied as myorg.io/metallb=true
    - name: worker-1
      role: worker
      address: 10.0.0.11

Node Roles:

| Role | Description | |------|-------------| | controller | Control plane only (no workloads) | | worker | Worker node only | | controller+worker | Combined control plane and worker |

Cluster Provisioning

Kustodian can provision Kubernetes clusters using pluggable providers. The default provider is k0s. Cluster provisioning is part of the apply command.

The provisioning process:

1. Validate - Check node definitions and SSH connectivity
2. Install - Provision Kubernetes via k0s/Talos/RKE2
3. Configure - Merge kubeconfig into ~/.kube/config
4. Wait - Wait for all nodes to reach Ready state
5. Label - Apply configured node labels

Plugins

Plugins extend Kustodian's functionality. They can:

• Generate resources - Create additional Kubernetes resources (e.g., Authentik SSO blueprints)
• Provide secrets - Integrate with secret managers (e.g., Doppler, 1Password)
• Validate configs - Add custom validation rules
• Transform resources - Modify resources before output

# Using plugins in a cluster
spec:
  plugins:
    - name: authentik-blueprints
    - name: doppler-secrets
      config:
        project: my-project

Packages

Kustodian is built as a collection of packages:

| Package | Description | |---------|-------------| | @kustodian/core | Core utilities, error handling, Result type | | @kustodian/schema | JSON Schema definitions for YAML validation | | @kustodian/loader | YAML file loading and validation | | @kustodian/cli | CLI framework with DI and middleware | | @kustodian/nodes | Node definitions, roles, and labeling | | @kustodian/bootstrap | Cluster bootstrap orchestration | | @kustodian/plugins | Plugin system infrastructure | | @kustodian/generator | Template processing and Flux generation |

Official Plugins

| Plugin | Description | |--------|-------------| | @kustodian/plugin-k0s | k0s cluster provisioning (built-in) | | @kustodian/plugin-authentik | Generate Authentik SSO blueprints | | @kustodian/plugin-doppler | Doppler secret management | | @kustodian/plugin-1password | 1Password secret management |

Installation

# Install the CLI
bun install -g @kustodian/cli

# Or use with bunx
bunx @kustodian/cli generate --cluster production

Usage

Initialize a New Project

kustodian init my-infrastructure
cd my-infrastructure

This creates:

my-infrastructure/
├── templates/
│   └── example/
│       ├── template.yaml
│       └── deployment/
│           └── kustomization.yaml
├── clusters/
│   └── local/
│       ├── cluster.yaml
│       └── nodes.yaml
└── kustodian.yaml

Validate Configurations

# Validate all templates and clusters
kustodian validate

# Validate a specific cluster
kustodian validate --cluster production

Apply Full Configuration

# Preview pending cluster changes first
kustodian diff --cluster production

# Apply complete cluster setup (bootstrap + Flux + templates)
kustodian apply --cluster production

# Use a different provider
kustodian apply --cluster production --provider talos

# Preview without making changes
kustodian apply --cluster production --dry-run

# Skip specific phases
kustodian apply --cluster production --skip-bootstrap
kustodian apply --cluster production --skip-flux
kustodian apply --cluster production --skip-templates

Documentation

• Getting Started Guide
• Template Reference
• Plugin Development
• API Reference

Contributing

We welcome contributions! See CONTRIBUTING.md for details on:

• Development setup
• Code style (follows OneZero Handbook)
• Pull request process
• Testing requirements (80% coverage minimum)

License

MIT License - see LICENSE for details.

Acknowledgments

Kustodian builds on the excellent work of:

• Flux CD - GitOps toolkit for Kubernetes
• Kustomize - Kubernetes configuration management
• k0s - Zero friction Kubernetes
• k0sctl - k0s cluster management tool