Skip to main content

Kairon documentation

The root README is the product landing page. This docs/ tree is authoritative for install, runbooks, guides, and status detail.

Start here​

I want to…Read this
See the product landingRoot README
Install and run a first Machinegetting-started.md
Deploy to a host in one command, no local buildgetting-started.md#fastest-path
Check that it all worksguides/selftest.md (kaironctl selftest)
See what's new in v0.10.4 and how to upgradeRELEASE_NOTES.md (v0.10.4 hardening patch and its upgrade notes; v0.10.0: agent sessions, agent sandboxes, cross-cluster DR, Mac Fabric, GPUs, DRS, NVMe-oF, HTTPS and console TLS by default)
Upgrade or roll back an install (CRDs first, keep your values)getting-started.md#upgrade-rollback-and-node-drains
Install for production (webhook TLS Secret, migration Secrets)getting-started.md#evaluation-vs-production
Find the kaironctl verb for a virtctl commandCLI.md#coming-from-virtctl
Give an AI coding agent its own VMguides/agent-sessions.md · guides/agent-sandboxes.md
Ten-minute architecture tour../ARCHITECTURE.md
Deep architecture referencearchitecture.md
Rehearse upgrades, recover applications, test incident fixes and plan placementguides/advanced-operations.md
Full feature inventoryWHAT_SHIPS.md
CLI referenceCLI.md
Dependency policyDEPENDENCIES.md
Release status & production gapsSTATUS.md
Hardware / lab matrixCOMPATIBILITY.md
Roadmap../ROADMAP.md
Migration failures / NeedsRecoveryrunbook-migration-failures.md
Lab runner, cluster access, adding a noderunbook-lab-setup.md
Security / threat model../SECURITY.md
Contributing../CONTRIBUTING.md

Documentation map​

DocCovers
ARCHITECTURE.mdThe ten-minute tour: components, request flow, trust boundaries/deployment topology, design rationale
deploy/Install paths: Helm, one command to a host, kind, air-gapped, macOS
RELEASING.md · STABILITY.mdHow a release is cut and checked; the GA and Experimental labels and how CI enforces them
TEST_REPORT.mdWhat was and was not verified per release (read this before trusting a claim)
getting-started.mdInstall, first Machine, cold migrate, live migration, the dashboard, Network Fabric
tutorials/machine-lifecycle.mdNarrated walkthrough: one Machine through create → relocate → snapshot → restore
architecture.mdDeep reference: the cold/live migration state machines, session durability, CSI/DRA mechanics, operational visibility
migration-adapter.mdThe migration adapter HTTP contract, trust boundary, the real kairon-migration-adapter-fluxvm implementation
network-fabric.mdMachineNetworkPolicy/NetworkSecurityGroup, FluxVM eBPF edge, opt-in Cilium ExternalWorkload attach and CNP sync
macos.md · macos-cluster.mdKairon on Apple silicon: Mac as a Node, vz Machines, verified vs not, Mac mini to Mac Studio cluster
ecosystem/README.mdDeveloper ecosystem kit: SDKs, recipes, GitHub Actions, Terraform
ebpf-edge.mdVM edge enforced by FluxVM: anti-spoof, learn-IP, QoS, DNS/SNI allow lists, attributed drops and metrics, packet capture, conntrack move on live migration
tutorials/network-fabric.md · guides/machine-network.md · guides/network-policy.mdNetwork Fabric walkthrough and field-level guides
guides/machine-quotas.md · guides/machine-disruption-budgets.mdMachineQuota/MachineDisruptionBudget reference, including the admission webhook
runbook-migration-failures.mdDiagnosing and resolving NeedsRecovery, alert-to-runbook cross-references
guides/machine-fencing.mdNodeUnreachable/Fenced conditions, kaironctl fence's safety model, storage/network migration preflight labels
ai-agents.md · guides/hermes-mcp.mdAI agent integration over MCP (Hermes Agent, Claude Code, Cursor): Kairon and FluxVM servers, scoped credentials, workflows; kaironctl mcp serve reference; MCP Registry (OCI) install
guides/agent-plane.mdAgent plane: sealed claims, strict egress compiler, edge Warning events and per-Machine traffic baselines, cosign image verification, SEV-SNP/TDX attestation, the audited MCP write path, and the proposal-only AI assistant (ask) and diagnose
guides/kairon-ui-dashboard.mdThe web console: sign-in and default-password banner, namespace selector and all-namespaces Machines view, table filter, bulk power actions, navigation and command palette, per-resource pages, machine inspector operations, node tools
guides/kairon-ui-api.mdEvery kairon-ui route with its access model (roles, namespace scoping, console tickets, unauthenticated image blobs)
guides/kairon-ui-ha.mdRunning ui.replicaCount > 1: what's shared, how, and its real limits
guides/kairon-controller-ha.mdRunning controller.replicaCount > 1: Lease-based leader election, RBAC, bare-metal setup
guides/observability.mdWhat each component's /metrics exposes, the kairon-health alert group, and the renamed PrometheusRule
guides/machine-migration-tls.mdControl-plane vs. data-plane migration TLS, and real per-node data-plane identity via migration.dataplaneTlsSecretName
guides/kairon-ui-oidc.mdOIDC/SSO setup, the Authorization Code + PKCE flow, and why it breaks Go-stdlib-only
guides/kairon-ui-console-rbac.mdReal Kubernetes RBAC (machines/console + SubjectAccessReview) for console access, opt-in alongside the annotation allowlist
guides/machine-storage.md · guides/machine-storage-csi.mdPVC-backed boot disks; Kairon's own first-cut CSI driver (iSCSI and NVMe-oF) and why it breaks Go-stdlib-only
guides/disk-qos.mdPer-disk IOPS and bandwidth limits (spec.image.io.throttle, spec.disks[].io.throttle) enforced by QEMU and changed live; why virtiofs DAX is not available
guides/machine-storage-nvmeof.mdNVMe-oF volumes (nvme-tcp, nvme-rdma, native multipath), raw Block boot in place, per-disk QEMU I/O and the StoragePaths condition (experimental)
guides/machine-storage-atlas.mdspec.volumes[].atlas: controller provisions Machine disks through Atlas (PVC or raw RBD), gates scheduling on readiness, releases after runtime cleanup
guides/machine-storage-thirdparty-csi.mdnode.thirdPartyCSIDrivers: kairon-node as a generic CSI client against an allowlisted third-party driver, including attachRequired drivers (VolumeAttachment) and namespace-allowlisted node secrets
guides/migrate-from-vmware.mdMoving VMware VMs to Kairon: kaironctl import ova, offline virtio repair, checklist
guides/machine-image-import.mdspec.image.source: downloading a remote image URL into kairon-node's own digest-keyed cache
guides/machine-images.mdMachineImage: a cluster-scoped, versioned catalog of boot disks and ISOs, pinned into a Machine by digest once
guides/machine-install-media.mdspec.cdroms + spec.image.blank: install Windows or Linux from an ISO onto an empty disk
guides/machine-sets.mdMachineSet: replica reconciliation, RollingUpdate/Recreate rollout strategy
guides/agent-sandboxes.mdspec.lifecycle idle suspend, wake on connect and max lifetime; paused warm pools; per-claim usage; the SDK Sandbox class
guides/agent-sessions.mdAgentSession: FluxVM agent sessions with workspace, policy, checkpoints, forks, jobs, files, git, previews and an exportable trajectory; admin approvals, chunked uploads, an interactive shell, credential grants, and the Mac guest's screen and input (experimental)
guides/machine-fork.mdkaironctl fork / fork_machine: live copies of a Running Machine from one memory snapshot
guides/machine-pools.mdMachinePool / MachineClaim: warm, pre-booted Machines claimed in one reconcile tick
guides/machine-instance-types.mdMachineInstanceType: a reusable named CPU/memory shape resolved into spec.resources once
guides/machine-cpu-numa.mdspec.resources.numaNode/.cpuSet/.hugepages: qemu-only NUMA/hugepage passthroughs, and what they don't guarantee (no real host-core pinning)
guides/machine-elastic-memory.mdspec.resources.elasticMemory: virtio-balloon reclaim under host memory pressure, a node memory overcommit ratio, the KaironMemoryPressure condition and opt-in evacuation (experimental)
guides/virtual-networks.mdVirtualNetwork: isolated IPv4 networks routed in eBPF with a Geneve overlay, controller IPAM, egress SNAT, floating IPs and an announce-only BGP speaker (experimental)
guides/machine-topology.mdspec.topology + spec.devices + NodeTopology: NUMA, GPU, NIC and NVMe locality with hard placement policies and bound guest NUMA memory (experimental)
guides/accelerator-profiles.mdMachineAcceleratorProfile and spec.accelerators: named accelerator shapes (count, vGPU profile, memory per device, p2pRequired, sameNuma, RDMA NIC) expanded into spec.devices before scheduling, with per-node capacity in status (experimental)
guides/gpu-vgpu.mdspec.devices[].profile: vGPU (mdev) and MIG-backed profiles scheduled by free instances and GPU memory, created and removed with the Machine; GPU health in NodeTopology and VRAM metrics (experimental)
guides/mac-fabric.mdSeveral Macs as one pool: Apple capability labels, spec.apple scheduling, MacNetwork private networks across Macs over Thunderbolt, kaironctl mac (experimental)
guides/cross-cluster-dr.mdMachineProtectionPlan: replicate Machines to a second cluster, RPO/RTO objectives, ordered failover and failback with epoch fencing, DR tests into an isolated bridge (also scheduled), kept VirtualNetwork addresses and external-dns records on failover, kaironctl dr (experimental)
guides/machine-cpu-pinning.mdspec.resources.cpuPinning: real exclusive host-core allocation, and the pinnable-cpus node label it depends on (operator-set or discovered by kairon-node)
guides/machine-windows-guests.mdWhat Windows guest support covers today (legacy-BIOS + cloudbase-init, and now UEFI Secure Boot/vTPM for Windows 11 given a node-configured OVMF vars template)
guides/migration-policies.mdMigrationPolicy: selector-scoped migration bandwidth defaulting and concurrency caps
guides/machine-snapshot-quiesce.mdReal guest fsfreeze/fsthaw around MachineSnapshot, and the controller↔node coordination protocol behind it
guides/machine-backup.mdFull disk backups with guest fsfreeze (MachineBackup) through FluxVM or Atlas S3, and in-place restore (MachineBackupRestore)
guides/machine-backup-incremental.mdIncremental S3 backups with changed-block tracking, MachineBackupPolicy schedules, GFS retention, synthetic fulls, encryption and Object Lock (experimental)
guides/machine-snapshot-restore.mdRestoring a MachineSnapshot volume into a new PersistentVolumeClaim via the standard CSI dataSource flow
guides/machine-pause-resume.md · guides/machine-halt.mdspec.powerState: Paused/Halted: suspending guest CPUs vs. powering off the VMM process while FluxVM keeps its record
guides/machine-incident-bundle.mdkaironctl diagnose machine --deep: one tar.gz with the Machine's cluster state and FluxVM's QMP, cgroup, console, dataplane and pcap from its node, redacted by default, plus an opt-in guest memory dump (experimental)
guides/machine-hibernate.mdspec.powerState: Hibernated: saving RAM and device state to disk, freeing the node, and resuming the same boot here or on a compatible node (experimental)
guides/machine-hotplug.mdGrowing spec.resources.cpu/.memory (kept across stop/start, hotplug-persist), and hot-attaching PVC disks (spec.disks) and extra NICs (spec.network.extraInterfaces) on a Running Machine
guides/node-maintenance-drs.mdNode maintenance mode (cordon, migrate or park Machines, restore on exit) and DRS rebalancing by reserved CPU and memory or measured pressure (PSI): kaironctl node maintenance, kaironctl drs plan, -drs-mode (experimental)
guides/preemption.mdOpt-in preemption: a pending higher-priority Machine halts an opted-in lower-priority one, which resumes when the preemptor is gone
guides/tenant-fence.mdspec.tenant + tenant-fence: east-west deny of other tenants' observed guest addresses in a namespace
guides/machine-resource-limits.mdspec.resources.limits: real, kernel-enforced cgroup v2 caps, and status.resourceUsage live usage
guides/machine-placement.mdScheduler internals: affinity/anti-affinity, weighted soft scoring, topologySpreadConstraints, DRA topology hints
guides/machine-sriov.mdSR-IOV NIC passthrough by reusing the existing GPU/VFIO DRA mechanism — why Multus doesn't apply to Kairon Machines at all
guides/machine-guest-agent.mdspec.guestAgent: real qemu-guest-agent-reported status.guestIP, including user/SLIRP networking
guides/machine-health-probes.mdspec.healthCheck: readiness and liveness probes (guest agent, TCP, exec), the Ready condition that gates kaironctl expose endpoints, and opt-in auto-restart with backoff and a cap
guides/machine-guest-exec.mdGuest exec (qemu-guest-agent), and the smaller API-only fsfreeze-status/firewall endpoints alongside it
guides/machine-guest-agent-files.mdGuest file access and the backend-agnostic vsock-agent guest exec, both over spec.guestAgent.console
guides/machine-port-forward.mdkaironctl port-forward, ssh and scp: reach a port inside a Machine through the console relay, without a Service or a route to the guest network
guides/machine-text-console.mdInteractive in-browser text console over FluxVM's own proprietary vsock guest agent
guides/machine-logs.mdStreaming a Machine's real captured serial console output -- Kairon's kubectl logs/-f equivalent
guides/machine-vm-state-snapshot.mdFull hypervisor-level VM-state checkpoint/restore (RAM, CPU, device state) -- distinct from MachineSnapshot's disk-content-only CSI snapshot
guides/container-sandboxes.mdspec.sandbox.oci and kaironctl container: run OCI images as FluxVM container sandboxes (macOS hosts), no Docker daemon, Podman or Colima
guides/machine-sandboxes.mdspec.sandbox: FluxVM's lightweight agent-sandbox track, templates, the HTTP proxy relay, warm pools, and the egress check
guides/machine-image-catalog.mdspec.image.catalogName: FluxVM's node-local, checksummed image catalog and its admin API
guides/machine-diagnostics.mdRuntime capabilities, PSI pressure, effective CPU set, and cgroup-level freeze/thaw
guides/crd-versioning.mdWhat the next CRD version bump after v1 still requires; the conversion webhook scaffold that exists today
runbook-multi-host-migration-test.md · runbook-recovery-drill.mdReal two-host live-migration testing; deliberately drilling a NeedsRecovery recovery
runbook-backup-restore.mdBacking up/restoring Kairon's CRD state (scripts/backup-crds.sh/restore-crds.sh), and what it doesn't cover (VM disk content, FluxVM host state)
runbook-velero-backup.mdUsing generic Velero (no Kairon-specific plugin) instead — what works out of the box, and the one real gap (no disk-content snapshot without a real CSI storage backend)
runbook-vm-export.mdGetting a Machine's disk content out of the cluster entirely, with standard Kubernetes primitives (no new Kairon-specific export tooling)
guides/enterprise-fleet.md · guides/enterprise-fleet-reference.mdExperimental, opt-in fleet automation (fleet.kairon.zyvor.dev): feature-status table, installation, trusted MCP action approvals, IPAM and usage accounting; and the field-level reference for those resources
guides/developer-ecosystem.mdDeveloper kit: dependency-free Python and TypeScript SDKs, deployment recipes, disposable-VM CI, Terraform manifests, orphan cleanup and qualification tooling
guides/machine-snapshot-schedules.mdMachineSnapshotSchedule: periodic or dailyAt snapshots by label selector, jitterSeconds, keepLast/maxAgeSeconds retention, manual trigger, missed-run deadline
guides/kaironctl-bulk-delete.md · guides/kaironctl-get-selector.md · guides/kaironctl-scale-selector.mdkaironctl delete, get and scale with --selector: act on, preview or scale every object matching a label selector
ebpf-performance-patch.mdPer-Machine partitioned eBPF drop-counter state and validated conntrack snapshots: what changed, and the measured bookkeeping cost
SUBSCRIPTION-MODEL.mdAnnual support subscription plans (Community, Standard, Supported, Enterprise) and terms; the software stays open source
OPENSSF_BEST_PRACTICES.mdOpenSSF Best Practices badge: where the evidence for each criteria area lives
design-cluster-api-provider.mdScoped, not built: what a real Cluster API infrastructure provider would take, and the real ownerReferences gap that blocks it today
ROADMAP.md · RELEASE_NOTES.mdWhat shipped per version, what's next; per-release changelog
SECURITY.mdThreat model, vulnerability reporting
CONTRIBUTING.mdPR checklist, coverage floor, frontend checks

Also in this tree​

DocCovers
guides/relocating-a-machine.mdCold/live migrate, evacuate, enable mTLS, cancel/delete/quiesce behavior
guides/admission-webhook.mdEnabling the ValidatingWebhook for quotas/budgets (README “Guarding the fleet”)
WHAT_SHIPS.mdFull feature inventory (was README “What ships today”)
CLI.mdFull kaironctl / kubectl kairon command reference (Cobra, embedded Helm, Krew)
DEPENDENCIES.mdStdlib-only controller/node vs named exceptions (CLI Helm, OIDC, CSI)
STATUS.mdv0.10.6 status + production gaps