One binary. Kubernetes APIs. Verifiable machines. Encrypted disks.

Kommodity packages Cluster API, Talos Linux providers, and hardware-rooted security services into a single binary so that compliant, multi-cloud Kubernetes clusters are as routine to deploy as any other workload.

---

Table of Contents

• Why Kommodity
• What's in the Box
• Architecture
• Features
• Quick Start
• Deployment
• Configuration
• CAPI Provider Versions
• Further Reading
• License

---

Why Kommodity

Sovereign cloud — keeping control of your infrastructure, your encryption keys, and your audit trail — usually means stitching together cloud-specific tooling, bespoke key management, and ad-hoc attestation. The result is fragile, expensive, and locked to whoever sold you "sovereign" first.

Kommodity takes the opposite approach: assemble proven, open-source building blocks (Cluster API, Talos Linux, Kine, TPM attestation) and ship them as a single binary that speaks the Kubernetes API. The same kubectl and Helm workflows work across Scaleway, Azure, KubeVirt, Docker, and bare metal.

Without Kommodity	With Kommodity
Learn each cloud's APIs, consoles, and quirks	One Kubernetes-native control plane for every provider
Trust machines because they're "on the network"	TPM-attested boot — no quote, no secrets
Cloud-provider KMS holds the encryption keys	Per-volume LUKS keys live in your database
Different ops model per environment	Same GitOps, RBAC, and audit logs everywhere
Compliance bolted on after deployment	Encryption, attestation, and audit logging by default

---

What's in the Box

A single kommodity binary that combines:

• Kubernetes API server — built on k8s.io/apiserver with extension and aggregation layer support
• Cluster API controllers — cluster, machine, and machine-deployment lifecycle
• Talos Linux providers — bootstrap and control-plane providers for immutable nodes
• Kine — etcd shim that lets any supported SQL backend (PostgreSQL, MySQL, SQLite, NATS, …) replace etcd
• KMS service — networked LUKS2 key management with per-volume AES-256-GCM and AAD binding
• Attestation service — TPM 2.0 quote verification gated by per-cluster policy
• Metadata service — Talos machine config delivery, gated by attestation
• Talos proxy — HTTP CONNECT proxy that tunnels gRPC into private-network workload clusters
• Cluster autoscaler integration — scales MachineDeployment replicas based on pending pods
• Web UI — kubeconfig retrieval, cluster overview, machine deployment drill-down

---

Architecture

For the security architecture — TPM attestation flow and disk encryption key management — see SECURITY.md.

---

Features

One API, Any Cloud

Provision Kubernetes clusters with vanilla Cluster API resources. Today Kommodity ships with providers for Scaleway, Azure, KubeVirt, and Docker; CAPI's provider ecosystem means more can be added without touching Kommodity itself.

OIDC Authentication

Plug Kommodity into Google, Azure AD, or any other OpenID Connect provider. Group claims from the IdP map to authorization decisions; the KOMMODITY_ADMIN_GROUP you configure gets cluster-admin equivalence, alongside the standard system:masters. For local development, set KOMMODITY_INSECURE_DISABLE_AUTHENTICATION=true.

Audit Logging

Native support for the Kubernetes audit policy format. Point KOMMODITY_AUDIT_POLICY_FILE_PATH at a policy file and every API request is captured with user, source IP, timestamp, and (optionally) request/response bodies.

Hardware-Rooted Machine Trust

The attestation extension runs on every Talos node and submits a TPM-signed quote — covering Secure Boot, SELinux/AppArmor state, kernel lockdown, installed extensions, and PCR values — before the metadata service is willing to hand over machine configuration. A machine that can't prove what it booted gets no secrets.

Sovereign Disk Encryption

The KMS service implements the SideroLabs KMS gRPC API and seals LUKS2 keys for the STATE and EPHEMERAL partitions with AES-256-GCM. Each volume gets its own key and AAD nonce; the AAD binds the ciphertext to the node UUID and the requesting IP, so a leaked disk image is unreadable on its own. Key revocation is kubectl delete secret.

Talos Proxy

When the management plane manages clusters on private networks, the TalosControlPlane reconciler cannot reach Talos nodes directly on port 50000. A local HTTP CONNECT proxy intercepts those gRPC connections and tunnels them through a Kubernetes port-forward to a talos-cluster-proxy pod inside the workload cluster. End-to-end mTLS is preserved. See pkg/talosproxy for details.

Auto-Bootstrap

The auto-bootstrap extension turns control-plane bring-up into a no-touch operation: every candidate node runs the same deterministic leader-election algorithm (earliest boot time, lowest IP as tiebreaker) over peers discovered in the configured CIDR, the winner initializes etcd, and the rest join automatically. Private networks only.

Autoscaling

A cluster-autoscaler-compatible reconciler watches MachineDeployment replica counts and requeues until they converge, so the upstream cluster autoscaler can drive replicas the same way it would on any CAPI-managed cluster.

Web UI

The UI exposes the bits operators actually need without making them touch kubectl: per-cluster kubeconfig copy/download, an at-a-glance dashboard of clusters and machine counts, and a cluster detail page with machine-deployment breakdowns (including GPU pools) and health status. With Kommodity running, the overview is at /ui and the per-cluster page at /ui/clusters/<cluster-name>.

Overview — kubeconfig retrieval, cluster counts, and the clusters table:

Cluster details — health, versions, and per-cluster machine deployments with min/current/max replicas:

Storage Backends

Kommodity uses Kine, so any database supported by Kine can back the API server. PostgreSQL is the default and best-tested.

Cluster Addons

The kommodity-cluster Helm chart ships with a fully-fledged addon lifecycle engine: every addon is a uniform unit with its own install mode, idempotency condition, upgrade policy, hook scripts, and initial values — whether it's the built-in Cilium CNI or a chart you bring yourself.

Bundled addons

Addon	Default	Install mode	Namespace	What it gives you
Cilium	✅ enabled	HelmInstall	kube-system	eBPF CNI, kube-proxy replacement, Hubble UI/relay, BGP control plane
talos-cluster-proxy	✅ enabled	HelmInstall	talos-cluster-proxy	In-cluster gRPC proxy used by Kommodity to reach Talos nodes on private networks
ArgoCD	⬜️ opt-in	KubectlApply	argocd	GitOps control plane; install-once-then-adopt by default

Lifecycle controls (every addon)

Field	Purpose
lifecycle.install.mode	HelmInstall for chart releases or KubectlApply for plain manifests
lifecycle.install.condition	Skip re-install when a target resource already exists (required for KubectlApply)
lifecycle.upgrade.disable	After the initial install, leave the addon untouched — hand ongoing management to ArgoCD/Flux
namespace	Target namespace (defaults to the addon name)
chart.{repository,name,version}	Pinned OCI or HTTPS Helm chart coordinates
initialExtraValues	Values merged into the chart at first install only (immutable thereafter)
extraEnvs	Extra env vars on the installer job, including secretKeyRef for credentials
preInstallationScript / postInstallationScript	Shell hooks run around the install for migrations or bootstrap glue

Bring your own addon

Any Helm chart on any OCI/HTTPS registry is a first-class addon. Drop it under kommodity.addons.<name> and you get the same lifecycle, GitOps handoff, hook scripts, and credential injection as the built-ins. The pattern fits the "replace managed services with sovereign equivalents" use case — for example, CNPG instead of RDS/Cloud SQL, Strimzi instead of managed Kafka, Rook/Ceph instead of managed object storage:

kommodity:
  addons:
    cnpg:
      enabled: true
      namespace: cnpg-system
      lifecycle:
        install:
          mode: HelmInstall
        upgrade:
          disable: true # hand ongoing reconciliation to GitOps
      chart:
        repository: https://cloudnative-pg.github.io/charts
        name: cloudnative-pg
        version: 0.23.0
      initialExtraValues:
        monitoring:
          enabled: true

Set upgrade.disable: true on day one and your GitOps tool can "adopt" the release without Kommodity fighting it on every reconcile. See the default values.yaml for the full schema and per-addon examples.

---

Quick Start

Prerequisites

• A recent Go (we recommend gvm):

  gvm install go1.26.1 -B
  gvm use go1.26.1 --default

• Caddy for local TLS termination (bootstrapped by make setup).

• The kubectl oidc-login plugin if you want OIDC locally:

  kubectl krew install oidc-login

Run It Locally

git clone https://github.com/kommodity-io/kommodity
cd kommodity

# Boot PostgreSQL + Caddy, run code generation
make setup

# Build the UI (must run before `make run`)
make build-ui

# Run Kommodity
make run

Then point kubectl at it:

kubectl --kubeconfig kommodity.yaml api-resources
kubectl --kubeconfig kommodity.yaml create -f examples/namespace.yaml

A minimal kubeconfig for OIDC-authenticated local use:

apiVersion: v1
kind: Config
clusters:
  - name: kommodity
    cluster:
      server: https://localhost:5443
      insecure-skip-tls-verify: true
users:
  - name: oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1
        command: kubectl
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=ISSUER_URL
          - --oidc-client-id=YOUR_CLIENT_ID
          - --oidc-extra-scope=email
        interactiveMode: Always
contexts:
  - name: kommodity-context
    context:
      cluster: kommodity
      user: oidc
      namespace: default
current-context: kommodity-context

Useful Make Targets

make build                            # binary in bin/
make build-ui                         # UI assets (htmx/templates)
make run                              # run locally against the docker-compose stack
make teardown                         # tear down the docker-compose stack
make run-kubevirt-integration-test    # deploy a workload cluster on local KubeVirt
make run-scaleway-integration-test    # deploy a workload cluster on Scaleway (costs $$)
make run-helm-unit-tests              # helm unittest for charts/kommodity-cluster

Get a Workload Cluster's kubeconfig

From the UI (per-cluster copy/download), or from the CLI:

kubectl --kubeconfig kommodity.yaml get secrets <cluster>-kubeconfig -ojson \
  | jq -r '.data.value' | base64 -d > workload.kubeconfig

For talosctl:

kubectl --kubeconfig kommodity.yaml get secrets <cluster>-talosconfig -ojson \
  | jq -r '.data.talosconfig' | base64 -d > talosconfig
talosctl --talosconfig talosconfig kubeconfig -n <controlplane-ip>

---

Deployment

Helm — kommodity-cluster

Once Kommodity itself is running, deploy workload clusters with the kommodity-cluster chart:

# Provider credentials (Scaleway example)
kubectl --kubeconfig kommodity.yaml create secret generic scaleway-secret \
  --from-literal=SCW_ACCESS_KEY=<key> \
  --from-literal=SCW_SECRET_KEY=<secret> \
  --from-literal=SCW_DEFAULT_REGION=fr-par \
  --from-literal=SCW_DEFAULT_PROJECT_ID=<project-id>

# Render and apply
helm template my-cluster oci://ghcr.io/kommodity-io/charts/kommodity-cluster \
  -f values.scaleway.yaml | kubectl --kubeconfig kommodity.yaml apply -f -

A minimal values.scaleway.yaml:

kommodity:
  provider:
    name: Scaleway
    secret:
      name: scaleway-secret
  region: fr-par
  controlplane:
    replicas: 3
    sku: PLAY2-NANO
  nodepools:
    default:
      replicas: 2
      sku: PLAY2-NANO

Provider-specific examples (Scaleway, Azure, KubeVirt, Docker) live in charts/kommodity-cluster.

Terraform — Azure

The kommodity_azure_deployment module provisions Kommodity itself on Azure: VNet, PostgreSQL Flexible Server, Container App, Log Analytics, and a custom-domain HTTPS endpoint backed by an Azure-managed certificate.

See terraform/examples for end-to-end examples.

Single Binary

The binary itself has no hidden runtime dependencies beyond a PostgreSQL connection. Drop it on any host, point it at a database, and run.

---

Configuration

Kommodity is configured via environment variables.

Variable	Description	Default
KOMMODITY_PORT	Port for the Kommodity server	5000
KOMMODITY_BASE_URL	Base URL for the Kommodity server	http://localhost:5000
KOMMODITY_DB_URI	PostgreSQL connection URI	(none)
KOMMODITY_DEVELOPMENT_MODE	Enable development mode	false
KOMMODITY_INSECURE_DISABLE_AUTHENTICATION	Disable authentication for local development	false
KOMMODITY_ADMIN_GROUP	Group name granted cluster-admin equivalence	(none)
KOMMODITY_OIDC_ISSUER_URL	OIDC issuer URL	(none)
KOMMODITY_OIDC_CLIENT_ID	OIDC client ID	(none)
KOMMODITY_OIDC_USERNAME_CLAIM	OIDC claim used for the username	email
KOMMODITY_OIDC_GROUPS_CLAIM	OIDC claim used for groups	groups
KOMMODITY_INFRASTRUCTURE_PROVIDERS	Comma-separated providers to enable	all
KOMMODITY_ATTESTATION_NONCE_TTL	TTL for attestation nonces (e.g. 5m, 1h)	5m
KOMMODITY_AUDIT_POLICY_FILE_PATH	Path to a Kubernetes audit policy file	(none)
KOMMODITY_TALOS_PROXY_ENABLED	Enable the HTTP CONNECT Talos gRPC proxy	true
KOMMODITY_TALOS_PROXY_PORT	Local listen port for the proxy	15050
KOMMODITY_TALOS_PROXY_NAMESPACE	Namespace of the talos-cluster-proxy service in workload clusters	talos-cluster-proxy
KOMMODITY_TALOS_PROXY_SERVICE_NAME	Name of the talos-cluster-proxy service	talos-cluster-proxy
KOMMODITY_TALOS_PROXY_IDLE_TIMEOUT	Idle timeout before unused tunnels are closed	1m
KOMMODITY_GARBAGE_COLLECTOR_ENABLED	Enable the embedded garbage collector	true
KOMMODITY_GARBAGE_COLLECTOR_WORKERS	Number of garbage collector workers	5
KOMMODITY_GARBAGE_COLLECTOR_SYNC_PERIOD	Resync period for the garbage collector	30s
KOMMODITY_GARBAGE_COLLECTOR_INITIAL_SYNC_TIMEOUT	Timeout waiting for initial informer sync	60s

Provider settings are managed in pkg/provider/providers.yaml: name, repository, Go module, CRD filter/deny lists, and API scheme locations. Providers must be compatible with Cluster API v1.10.x.

---

CAPI Provider Versions

Provider	Version	Type
cluster-api	v1.10.10	Core
cluster-api-control-plane-provider-talos	v0.5.13	Control Plane
cluster-api-bootstrap-provider-talos	v0.6.12	Bootstrap
cluster-api-provider-scaleway	v0.1.5	Infrastructure
cluster-api-provider-kubevirt	v0.1.10	Infrastructure
cluster-api-provider-azure	v1.21.0	Infrastructure

Limitations

• Helm hooks are not supported.

---

Further Reading

• SECURITY.md — disk encryption and machine trust internals
• Talos Linux Documentation
• Cluster API Documentation
• Kine — etcd shim for SQL databases
• Attestation Extension
• Auto-Bootstrap Extension

---

License

Kommodity is licensed under the Apache License 2.0.