Skip to main content

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 a 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.

In this guide, we'll be using kairos-lab, a simple tool to create and manage Kairos virtual machines.

Windows

kairos-lab does not run on Windows. If you're on Windows, use VirtualBox or another virtualization software instead.

Installing kairos-lab​

brew tap kairos-io/kairos
brew install kairos-lab

Once installed, run the setup command to install any required dependencies (like QEMU):

kairos-lab setup

Prefer to watch a video?​

Download an ISO​

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.

Download the latest Kairos ISO using kairos-lab:

kairos-lab download

If you prefer to download an artifact manually, visit the latest releases page.

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)

ProfileDiskRAMDescription
Bare-minimum8 GB2 GBBoots Hadron with k3s and allows very small demo workloads. Intended only for constrained environments and smoke tests.
Practical minimum16 GB4 GBRecommended starting point for demos, labs, and PoCs. Enough capacity to run several demo applications without constant cleanup.
Recommended playground32 GB8 GBBest for richer demos including small databases, dashboards, and multiple apps. Still non-production, but feels like a real mini-cluster.

Start a new VM with kairos-lab:

kairos-lab start

You will be prompted to provide a name for your VM (or press Enter to use the default). You can then configure the VM resources as you prefer, or accept the defaults.

Important: Keep the bridged network option enabled, as this is required for the VM to obtain an IP address accessible from your browser. Before the VM can start, kairos-lab will need to create a bridged network, which requires sudo privileges.

Installing the OS​

  1. 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

  2. Add the following configuration to the web installer

    #cloud-config
    users:
    - name: kairos
      passwd: kairos
      groups: [admin]
    k3s:
      enabled: true

  3. In the device field, type "auto"

  4. Check on "Restart after installation"

  5. 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?​

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) quickstart

Deep dive docs​

If you're already comfortable with Kairos and want details, jump straight to the reference docs.

Cloud-config reference

BYOI and custom pipelines

Frequently 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.

Last updated on by Mauro Morales