What is KubeOne? Automated Kubernetes Lifecycle Management

Introduction

Setting up a Kubernetes cluster is not the hard part anymore. Tools like kubeadm, managed services, and one-click installers have made day-1 straightforward. The hard part is everything after that: upgrading Kubernetes versions without downtime, replacing failed nodes at 2 AM, rotating certificates before they expire, patching CVEs across your control plane and workers. That is where most teams burn time — and where most tools leave you on your own.

KubeOne is Kubermatic’s open-source tool that automates the full lifecycle of Kubernetes clusters: installation, upgrades, and repair. It works on any infrastructure where you can reach servers over SSH — AWS, GCP, Azure, Hetzner, bare metal, edge locations, or the server rack in your basement. You describe your desired cluster state in a YAML file, and KubeOne makes it happen.

KubeOne is licensed under Apache 2.0 and fully open source. No enterprise paywall for core functionality.

What is KubeOne?

KubeOne is a CLI tool that manages the complete lifecycle of Kubernetes clusters. You run kubeone apply, and it handles installation, configuration, upgrades, and repairs — all from a single declarative manifest.

Built by Kubermatic, the company behind the Kubermatic Kubernetes Platform (KKP), KubeOne was designed to solve a specific problem: automating Kubernetes operations on infrastructure that managed services do not reach. If you have SSH access to a server, KubeOne can turn it into a Kubernetes node.

Under the hood, KubeOne uses kubeadm — the official Kubernetes bootstrapping tool. What KubeOne adds on top is automation, declarative configuration, Terraform integration, and day-2 operations. Instead of running a dozen kubeadm commands manually and hoping you got the flags right, you define your cluster in YAML and let KubeOne execute the correct sequence every time.

KubeOne handles both day-1 and day-2 operations:

Day-1: Provision the container runtime, bootstrap the control plane with kubeadm, set up etcd, deploy networking and cloud integrations, create worker nodes.
Day-2: Detect version drift, perform rolling upgrades of control plane and worker nodes, repair broken nodes, manage addons, rotate certificates.

How KubeOne Works

KubeOne’s architecture is straightforward. Four components work together to take you from bare servers to a running cluster.

KubeOneCluster Manifest

Everything starts with a YAML file called the KubeOneCluster manifest. This file declares your desired cluster state: the Kubernetes version you want, which cloud provider you are targeting, control plane host addresses, networking configuration, and any addons you want deployed. This file is your single source of truth. Version control it, review it in pull requests, and apply it with confidence.

Terraform Integration

KubeOne does not provision infrastructure. That is Terraform’s job, and KubeOne stays out of its way. Instead, KubeOne reads Terraform output to discover your infrastructure — server IPs, SSH keys, load balancer addresses, cloud-specific metadata. You run terraform apply to create servers, then terraform output -json feeds that information to KubeOne.

Kubermatic maintains official Terraform examples for every supported cloud provider in the KubeOne GitHub repository. These are production-tested configurations you can use directly or adapt to your needs.

Tip: You can skip Terraform entirely and specify hosts manually in the KubeOneCluster manifest. This is common for bare metal setups where servers already exist and you just need KubeOne to install Kubernetes on them.

SSH-Based Execution

KubeOne connects to your servers over SSH, installs the container runtime (containerd), bootstraps kubeadm, and configures the cluster. There is no agent to install, no daemon to maintain, no control plane running on your laptop. KubeOne runs, does its work over SSH, and exits. The next time you run it, it connects again, compares actual state to desired state, and makes any necessary changes.

machine-controller

Once the control plane is up, KubeOne deploys machine-controller — a Kubernetes-native controller that manages worker nodes declaratively. You define MachineDeployment resources (similar to Deployments, but for machines), and machine-controller provisions and joins worker nodes automatically. Need to scale from 3 to 10 workers? Update the replica count. Need to rotate all workers to a new OS image? Update the spec and machine-controller rolls them out.

The Full Flow

flowchart LR
    TF[Terraform
provisions servers]
    Manifest["KubeOneCluster
manifest (YAML)"]
    K1["kubeone apply
(your laptop / CI)"]

    TF -->|terraform output| K1
    Manifest --> K1

    K1 -->|SSH| CP["Control-plane nodes
(kubeadm init/join)"]
    CP --> Cluster[(Running cluster)]
    Cluster --> MC[machine-controller]
    MC -->|manages| Workers[Worker nodes
via MachineDeployment]

Key Features

Multi-provider support. AWS, GCP, Azure, Hetzner Cloud, DigitalOcean, OpenStack, Equinix Metal, VMware vSphere, Nutanix, and bare metal. If you can SSH into it, KubeOne can manage it.

Automated upgrades. Run kubeone apply with a new Kubernetes version in your manifest. KubeOne detects the version drift and performs a rolling upgrade — control plane nodes first, then workers. No manual draining, no manual kubeadm upgrade commands, no crossing your fingers.

HA control planes. Three control plane nodes with etcd distributed across them, configured out of the box. KubeOne handles the etcd bootstrapping and join process that is notoriously tricky to do by hand.

Addon system. Deploy CNI plugins (Canal, Cilium), CSI drivers, cloud controller managers, and your own custom addons as part of the cluster lifecycle. Addons are applied on every kubeone apply run, so drift is corrected automatically.

Declarative configuration. One YAML file describes your entire cluster. No imperative commands to remember, no sequence of steps to get right. Declare what you want, apply it, and KubeOne figures out how to get there.

Encrypted secrets. KubeOne integrates with credential providers so your cloud API keys and SSH keys are never stored in plaintext in your manifest.

When Should You Use KubeOne?

Bare Metal and Budget Clouds

You have servers — maybe Hetzner, maybe Equinix Metal, maybe physical machines in a datacenter. You need Kubernetes but managed services like EKS or GKE are not an option (wrong provider, too expensive, or simply not available for your infrastructure). KubeOne gives you a production-grade, HA Kubernetes cluster on any hardware, with automated upgrades included.

Edge and IoT

You need Kubernetes running at remote locations — factory floors, retail stores, cell towers, oil rigs. These environments typically have limited connectivity and no cloud API to call. KubeOne automates what would otherwise be manual SSH-and-pray operations: install Kubernetes, upgrade it months later when a maintenance window opens, repair it when a node fails.

Multi-Cloud Consistency

Your organization runs workloads across AWS, GCP, and on-prem. You want the same Kubernetes operational workflow everywhere. With KubeOne, you use the same tool, the same manifest structure, and the same kubeone apply command regardless of where the cluster lives. Only the Terraform layer changes.

KubeOne vs Other Tools

Tool	Cloud Support	Bare Metal	Day-2 Ops	Approach	License
KubeOne	All major clouds	First-class	Automated upgrades	Declarative YAML + SSH	Apache 2.0
kubeadm	Any	Yes (manual)	Manual	Imperative CLI	Apache 2.0
kOps	AWS (primary), GCP	No	Rolling updates	Declarative, cloud-native	Apache 2.0
Rancher/RKE2	All major clouds	Yes	Through Rancher UI	Rancher-managed	Apache 2.0
Cluster API	All major clouds	Experimental	Declarative	Kubernetes-native (CRDs)	Apache 2.0

The main difference: KubeOne is the only tool that treats bare metal and cloud infrastructure equally, with full day-2 lifecycle automation. kubeadm gives you the building blocks but no automation. kOps is excellent for AWS but does not support bare metal. Cluster API is powerful but requires an existing management cluster and has limited bare metal support.

Tip: KubeOne and kOps serve different audiences. If you are AWS-only and want deep AWS integration, kOps is excellent. If you need bare metal, multi-cloud, or edge support, KubeOne is the better fit. See KubeOne vs kOps for a detailed comparison.

The Terraform Connection

The relationship between KubeOne and Terraform deserves emphasis because it is central to how you will use KubeOne in practice.

KubeOne deliberately does not provision infrastructure. Creating VMs, setting up load balancers, configuring networks — that belongs to Terraform (or your infrastructure tool of choice). This separation keeps both tools focused: Terraform manages infrastructure, KubeOne manages Kubernetes.

The workflow looks like this:

Write Terraform configuration for your infrastructure (or use one of the official examples from the KubeOne repository).
Run terraform apply to create servers, load balancers, and networks.
Run terraform output -json > tf.json to export infrastructure details.
Run kubeone apply --manifest kubeone.yaml -t tf.json to install Kubernetes.

When you need to upgrade Kubernetes, you update the version in your KubeOneCluster manifest and run kubeone apply again. When you need to add more servers, you update your Terraform configuration, apply it, and run kubeone apply to pick up the changes.

For bare metal environments where servers already exist, you skip Terraform entirely and list your hosts directly in the KubeOneCluster manifest with their IP addresses and SSH credentials.

Next Steps

You now understand what KubeOne is, how it works, and where it fits. The next step is to get your hands on it.

Installing KubeOne: Your First Cluster in 15 Minutes — the next tutorial in this series walks you through installing KubeOne and provisioning your first cluster end-to-end.
If you already have bare metal servers ready, jump to Zero to Production: KubeOne on Bare Metal for a hands-on guide.
For Hetzner Cloud users, the Hetzner-specific guide covers provider configuration and cost-optimized setups.

Summary

KubeOne automates the full lifecycle of Kubernetes clusters — installation, upgrades, and repair — on any SSH-reachable infrastructure. It pairs with Terraform for infrastructure provisioning, uses kubeadm under the hood, and deploys machine-controller for declarative worker node management. If you need Kubernetes on bare metal, budget clouds, or edge hardware without paying for a managed service, KubeOne is the tool.