Butler Architecture

Butler is a Kubernetes-native platform built on CRDs and operators. All state lives in Kubernetes, enabling GitOps workflows and standard tooling.

System Context

Management Cluster Components

Component	Purpose	Repository
butler-controller	Reconciles TenantCluster, Team, ManagementAddon	butler-controller
butler-bootstrap	Reconciles ClusterBootstrap, MachineRequest	butler-bootstrap
butler-server	REST API and WebSocket for Console	butler-server
butler-console	Web UI (React)	butler-console
Steward	Hosts tenant control planes as pods	steward
Cluster API	Manages cluster infrastructure	External

Tenant Cluster Components

Each tenant cluster includes:

Component	Purpose
Cilium	CNI networking
MetalLB	LoadBalancer services
Longhorn	Distributed block storage (optional)
cert-manager	TLS certificate management
Traefik	Ingress controller (optional)

Key Flows

Bootstrap

Creates a management cluster from scratch:

1. User runs butleradm bootstrap
2. CLI creates temporary KIND cluster
3. Deploy bootstrap and provider controllers
4. Create ClusterBootstrap CR
5. Controller provisions VMs via provider
6. Install Talos Linux and bootstrap Kubernetes
7. Install platform addons
8. Save kubeconfig, delete KIND

Detailed bootstrap flow

Tenant Cluster Creation

Creates a tenant cluster:

1. User creates TenantCluster CR
2. Controller creates StewardControlPlane (hosted CP)
3. Controller creates CAPI Cluster and MachineDeployment
4. CAPI provisions worker VMs
5. Workers bootstrap and join cluster
6. Controller installs platform addons
7. Cluster transitions to Ready

Detailed tenant lifecycle

Addon Installation

Installs an addon on a cluster:

1. User creates TenantAddon CR
2. Controller retrieves AddonDefinition
3. Controller gets tenant cluster kubeconfig
4. Controller installs Helm chart
5. Addon transitions to Installed

Detailed addon system

IP Address Management

Allocates IP addresses to tenant clusters from shared pools:

1. Platform admin creates NetworkPool with CIDR range
2. ProviderConfig references pools via poolRefs
3. TenantCluster provisioning creates IPAllocation (Pending)
4. NetworkPool controller allocates IPs using best-fit algorithm
5. TenantCluster configures MetalLB with allocated ranges
6. On deletion, IPs return to the pool

IPAM internals

Detailed Documentation

Document	Description
Bootstrap Flow	Management cluster creation process
Tenant Lifecycle	Tenant cluster provisioning and management
Addon System	Addon catalog and installation
Multi-Tenancy	RBAC implementation and namespace isolation
IPAM Internals	Bitmap allocator, elastic scaling, garbage collection

Design Decisions

Architectural decisions live in design/adr/.

ADR	Decision
ADR-0002	Separate CLIs for operators (butleradm) and users (butlerctl)
ADR-0003	CRDs as the API contract
ADR-0004	Multi-repository architecture
ADR-0006	Hosted control planes by default