Hadron Quickstart
Objective
This guide shows how easy it is to deploy a Kubernetes cluster using Hadron by Kairos. To keep things quick and effective, we’ll pre-select a few choices for you. You’ll perform a traditional, interactive installation of a single-node cluster on an x86_64 virtual machine. At the end, you’ll find links to explore many other setup options.Ready to launch your Kubernetes cluster with ease? Hadron by Kairos makes it simple: download the ISO, start a virtual machine (VM), and follow a few guided steps. Whether you use Linux, Windows, or macOS, you’ll have a cluster running in no time.
Prerequisites
Alternatives
This tutorial uses the recommended virtualization tools to keep the instructions simple. Other alternatives should work as well, but they’re not documented here. If you successfully follow the tutorial using different tools, please consider opening a PR so others can benefit from your steps.To run Hadron Trusted Boot, you’ll need virtualization software that can run or emulate the amd64 architecture. In this guide, we’ll be using:
Prefer to watch a video?
Download an ISO
arm64
Hadron is still in beta, and for now only amd64 images are available. If your host system is arm64, you can still run amd64 virtual machines, but expect a performance hit. Keep this in mind for the demo.
For production setups, you can either use one of the other Kairos flavors or wait for the upcoming arm64 release.
Kairos Flavor
Kairos offers multiple flavors — different Linux distributions that power the immutable OS. Hadron is the default, engineered for image-based workflows, but you can also use Alpine, Debian, Fedora, Rocky, Ubuntu, and many more. In this quickstart, we’ll be using Hadron.Click the following link to download: kairos-hadron-0.0.1-standard-amd64-generic-v3.6.1-beta2-k3sv1.34.2+k3s1.iso
Create a Virtual Machine (VM)
KVM
Make sure you have KVM enabled in your virtualization software; this will improve the performance of your VM significantly.Requirements
Hadron Single-Node Demo Requirements (with k3s)
| Profile | Disk | RAM | Description |
|---|---|---|---|
| Bare-minimum | 8 GB | 2 GB | Boots Hadron with k3s and allows very small demo workloads. Intended only for constrained environments and smoke tests. |
| Practical minimum | 16 GB | 4 GB | Recommended starting point for demos, labs, and PoCs. Enough capacity to run several demo applications without constant cleanup. |
| Recommended playground | 32 GB | 8 GB | Best for richer demos including small databases, dashboards, and multiple apps. Still non-production, but feels like a real mini-cluster. |
- Click New to create a virtual machine.
- Fill in the VM details:
- Name: Hadron
- ISO Image:
/FULL/PATH/kairos-hadron-0.0.1-standard-amd64-generic-v3.6.1-beta2-k3sv1.34.2+k3s1.iso - OS: Linux
- OS Distribution: Other Linux
- OS Version: Other Linux (64-bit)
- Configure the VM resources:
- Base Memory: 2048 MB (enough for this quickstart; for applications, consider 4 or 8 GB)
- Number of CPUs: 1 (increase if your host has spare capacity)
- Disk Size: 8 GB (sufficient for this quickstart; increase if you plan to deploy more workloads)
- Use EFI: disabled
- In the VM list, select the Hadron VM and click Settings.
- Go to System and adjust the Boot Order (BIOS only) so Hard Disk is first and Optical comes after.
- Go to Network and configure:
- Attached to: Bridged Adapter
- Click OK to save your changes.
- With the Hadron VM selected, click Start.
- Create a new VM.
- Assign the downloaded ISO to the CD-ROM and set it as the boot media.
- Configure the VM hardware according to the requirements.
- Start the VM.
Installing the OS
After the machine boots, give it a bit until you see the designated machine IP and head to your browser and type http://IP:8080
Add the following configuration to the web installer
#cloud-config users: - name: kairos passwd: kairos groups: [admin] k3s: enabled: trueIn the device field, type “auto”
Check on “Restart after installation”
If the installation went correctly, the machine will eventually restart
Eject the CD!
Some virtualization software automatically removes the CD after installation. To avoid any confusion, make sure you have the right boot order as mentioned in the previous section. Otherwise, make sure to eject the CD before rebooting.First Boot
After the reboot you will again see the GRUB boot menu. This time the options don’t include any installation; instead, you can start the system in either active, passive (fallback), or rescue mode.
We will learn more about these options in the next steps. For now, just select the first option that only says Kairos and press Enter. If you don’t touch anything, the system will boot automatically after a few seconds.
After the system finishes booting, you will see a login prompt. Log in with the user kairos and the password you set during the installation.
SSH into the system
VM network
Accessing your VM via SSH will depend on your virtualization software network configuration. If you followed the configuration above, with a bridged card, your machine should get an IP within your network, allowing you to SSH in.We can use the same IP we used to install the system to ssh in:
ssh kairos@IP
Now enter the password you set during the installation.
Check Your Running Cluster
After logging in, you can check the status of the cluster with the kubectl tool. First switch to the root user with the following command:
sudo su -
Start by displaying the nodes in the system:
kubectl get nodes
You should see the k3s control-plane node listed, which is the machine you just provisioned.
NAME STATUS ROLES AGE VERSION
kairos Ready control-plane 164m v1.34.2+k3s1
If you display the pods within the kube-system namespace:
kubectl get pods -n kube-system
You should see the coredns and local-path-provisioner pods running. For example:
NAME READY STATUS RESTARTS AGE
coredns-7f496c8d7d-mjmkp 1/1 Running 0 170m
helm-install-traefik-crd-mqdfk 0/1 Completed 0 170m
helm-install-traefik-sr9b5 0/1 Completed 2 170m
local-path-provisioner-578895bd58-k667m 1/1 Running 0 170m
metrics-server-7b9c9c4b9c-kjdfn 1/1 Running 0 170m
svclb-traefik-fbdc293e-scdm4 2/2 Running 0 170m
traefik-6f5f87584-kjcdr 1/1 Running 0 170m
Conclusion
Congratulations 🎉 You have successfully deployed a Kubernetes cluster using Kairos Hadron 🚀 You can now start deploying your applications and services on your new cluster.
Please refer to the K3s documentation to learn more about the Kubernetes distribution that Kairos uses in the standard images.
What’s Next?
Continue the quickstart (recommended)
If you’re new to Kairos, follow these in order to learn the full workflow: extend the image, upgrade atomically, then harden the system.
Extend Hadron using a Dockerfile Upgrade & rollback (atomic upgrades) Trusted Boot (Secure Boot + Meassured Boot) quickstartDeep dive docs
If you’re already comfortable with Kairos and want details, jump straight to the reference docs.
Cloud-config referenceFrequently Asked Questions (FAQs)
How do I configure the system?
You can configure the system by editing the cloud-config file. The cloud-config file is located at /oem/90_custom.yaml. You can edit this file to add users, SSH keys, and other configurations. See the Cloud Config documentation for more information.
What is a Kairos flavor?
A Kairos flavor is a specific version of Kairos that is built on top of a specific Linux distribution. For example, the Alpine Kairos flavor is built on top of Alpine Linux. You can choose the flavor that best suits your needs. Once Hadron is stable, it will become the default flavor, but all the other flavors continue to be supported.
Can I use Kairos without Kubernetes?
Yes, absolutely! You can use Kairos as a standalone Linux distribution without Kubernetes. Just download the Kairos Core artifacts if you don’t want to use Kubernetes, or configure the Standard artifacts with the k3s option disabled.
Can I use a different Kubernetes distribution with Kairos?
Yes, you can download the standard image with k0s. Both k3s and k0s are equally supported by the Kairos team.