A GitOps templating framework for Kubernetes with Flux CD. Define templates in YAML, bootstrap clusters, and extend with plugins.
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
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. |
# 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# 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"# 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 full cluster configuration (bootstrap + Flux + templates)
kustodian apply --cluster productionThis bootstraps the cluster, installs Flux CD, and deploys your 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:
- operatorClusters 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 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.11Node Roles:
| Role | Description |
|---|---|
controller |
Control plane only (no workloads) |
worker |
Worker node only |
controller+worker |
Combined control plane and worker |
Kustodian can provision Kubernetes clusters using pluggable providers. The default provider is k0s. Cluster provisioning is part of the apply command.
The provisioning process:
- Validate - Check node definitions and SSH connectivity
- Install - Provision Kubernetes via k0s/Talos/RKE2
- Configure - Merge kubeconfig into
~/.kube/config - Wait - Wait for all nodes to reach Ready state
- Label - Apply configured node labels
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-projectKustodian 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 |
| 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 |
# Install the CLI
bun install -g @kustodian/cli
# Or use with bunx
bunx @kustodian/cli generate --cluster productionkustodian init my-infrastructure
cd my-infrastructureThis creates:
my-infrastructure/
├── templates/
│ └── example/
│ ├── template.yaml
│ └── deployment/
│ └── kustomization.yaml
├── clusters/
│ └── local/
│ ├── cluster.yaml
│ └── nodes.yaml
└── kustodian.yaml
# Validate all templates and clusters
kustodian validate
# Validate a specific cluster
kustodian validate --cluster production# 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-templatesWe welcome contributions! See CONTRIBUTING.md for details on:
- Development setup
- Code style (follows OneZero Handbook)
- Pull request process
- Testing requirements (80% coverage minimum)
MIT License - see LICENSE for details.
Kustodian builds on the excellent work of: