Install the platform

The KubeNest Platform is a pinned, tested bundle of everything a Kubernetes cluster needs above Kubernetes itself — ingress, certificates, storage, backup, upgrade orchestration and OS patching — installed together as one versioned unit onto Ubuntu hosts you supply.

This page covers installing that bundle onto machines that have no Kubernetes on them yet — and the control plane that manages the fleet. Every cluster registers to a control plane through the same API path. The first install creates the control plane inside the cluster it is installing and leaves the CLI logged in to it; every cluster after that registers to the same control plane.

What “one click” means here

The claim is deliberately narrow, because a claim we can test is worth more than a claim that sounds bigger:

From a single machine with SSH access to your target nodes, one command installs the complete core bundle in under fifteen minutes, with no further human steps.

What that does not mean:

• It does not provision machines. You supply the hosts, the network and the disks.
• It does not configure your DNS, your load balancer or your firewall.
• It does not mean nothing can fail. It means a failure names the component, the stage and the remedy — see When it fails.

Before you start

Supported hosts

Ubuntu 24.04 LTS only. That is the release the bundle is tested on. The installer refuses to run on any other release or any other distribution, rather than half-installing one.

Locking the operating system is what makes the bundle testable: a known kernel and a deterministic LVM layout are preconditions for the storage and OS-patching components, and for replicated storage later.

Host sizing

Preflight checks every node against these before anything is installed.

Preflight fails below the hard floor and warns below the recommendation. The floor is k3s’s own documented minimum plus headroom for the rest of core. The recommendation is what to buy if the cluster is going to carry real workloads.

The thresholds themselves live in the bundle manifest under limits.resources, so they are versioned with the release rather than compiled into the installer.

Disks and storage

The bundle uses OpenEBS Local PV LVM for persistent volumes. Replicated block storage is a profile, not core — it is itself a source of operational dread, and durability in the default configuration comes from verified backups plus application-level replication instead.

Local PV LVM provisions volumes out of an LVM volume group that must exist on each node that will host persistent data. There are two supported ways to get one, and you pick per install.

Option 1 — you create the volume group (default). Create a volume group named kubenest-vg on each data-bearing node before running the installer. Preflight verifies it exists and has free extents. The installer never touches your block devices.

This asks nothing extra of you in packaging terms: lvm2 ships on the stock Ubuntu 24.04 cloud image, so pvcreate and vgcreate are already present on a fresh host.

Option 2 — the installer creates it. Name a blank device explicitly:

--storage-device /dev/nvme1n1

The installer creates kubenest-vg on that device. Preflight refuses if the device holds a partition table, a filesystem or an existing volume group, so this cannot silently overwrite data. The flag is required — there is no device auto-detection, because guessing which disk is disposable on someone else’s infrastructure is not a risk worth taking.

Creating a volume group from free space on the root disk is not supported.

Which option you used is recorded against the cluster, because it determines what uninstall is allowed to remove.

Backup

Velero is installed as part of core. The install does not configure a backup target; where backups are written is yours to choose and configure after the cluster is up. See Backup and restore.

Network

Between cluster nodes:

Outbound from the cluster and from the machine running the installer:

• HTTPS to container registries and Helm repositories, for the duration of the install;
• TCP 443 to the management cluster, from the machine running the CLI, for the control plane API and console; and
• TCP 443 to the management cluster, from each cluster that is being added, because its agent opens the hub connection outbound as wss on that port.

The agent opens that connection outbound and holds it open, so it survives NAT and an egress-only firewall.

Access

The machine you run the installer from needs SSH to every target node, with passwordless sudo on each.

The installer uses your existing SSH setup: ~/.ssh/config, ssh-agent, or a key file named with --ssh-key. Key material stays on your machine and is never written to the installer’s logs.

Preflight runs sudo -n true on each node and fails with the exact remediation if it does not succeed. The default ubuntu user on official Ubuntu cloud images already has passwordless sudo configured by cloud-init, so on a stock AWS Ubuntu host this needs nothing from you.

An existing cluster on these hosts

Not supported. The installer builds new clusters only. Preflight refuses to run on any host where k3s, RKE2, kubelet or containerd is already present, and says so plainly.

Adopting a cluster that already exists means inheriting whatever ingress, CSI and cert manager are already installed on it — which is the untested component combination the bundle exists to eliminate. It is a different product and it is out of scope.

Choose your tiers before you run

Two choices are made at install time and recorded permanently against the cluster.

HA tier

single-server — one control-plane node running single-node embedded etcd, plus verified snapshots. Simpler, cheaper, fewer moving parts. The honest promise is “we restore, and the restore is drilled”, never “highly available”. Restore duration depends on your data volume, so the drill reports your own measured figure rather than quoting one.

Be clear on what a single-server control-plane failure actually does: running pods keep running, because the kubelet does not need the API server. But nothing new schedules, nothing self-heals, no deploy or scale succeeds, and any pod or node that dies is never replaced. Ingress keeps serving its last known configuration. The cluster is frozen, not down — until the second failure, which cascades with no recovery path.

ha — three control-plane nodes with etcd replicated across them. Survives the loss of one node. Triples control-plane cost and introduces etcd quorum operations.

Profiles

Core is always installed. Profiles are chosen at install and are the only supported way to vary what a cluster runs — free-form component toggles would mean 2^N test configurations instead of N+2.

Profiles, what changing one later does, and what it does not do, are covered on the Profiles page.

The install command

The installer is the kubenest CLI, run from your own workstation or bastion. Your SSH keys stay on your machine.

The first cluster

On the first cluster, --control-plane installs the platform bundle and the KubeNest control plane — console, API, hub, Postgres and Redis — into that cluster, registers the cluster to that control plane, and leaves the CLI logged in:

kubenest platform install \
  --control-plane \
  --bundle 1.1 \
  --name mgmt \
  --ha single-server \
  --server 10.0.1.10 \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_ed25519 \
  --storage-device /dev/nvme1n1

--domain is optional and defaults to <first --server address>.sslip.io. The console is served at https://app.<domain> and the API at https://api.<domain>. The certificate for those hostnames is issued by the cluster’s own platform CA, so a browser shows a certificate warning until you import that CA or configure your own issuer; the CLI stores the CA automatically. --admin-email is optional and defaults to admin@<domain>. The installer prints the generated admin password once — save it.

Every cluster after that

With the CLI logged in, drop --control-plane and install the platform on the next cluster:

kubenest platform install \
  --bundle 1.1 \
  --name client-a \
  --ha single-server \
  --server 10.0.2.10 \
  --ssh-user ubuntu \
  --storage-device /dev/nvme1n1

The new cluster’s agent connects out to the management cluster’s hub over wss on 443, so the management host must accept 443 from the new cluster and from the machine running the CLI. On a machine that has not logged in, run kubenest login --control-plane https://api.<domain> --token-stdin --ca-file <platform CA> first.

The management cluster is registered through the API like every other cluster, and the control plane it runs is the one the whole fleet registers to.

--bundle selects the platform version. Every component version is pinned by that number — the bundle is the unit of test, of support and of upgrade, and a cluster is always at exactly one bundle version plus a recorded profile set. Install Platform 1.1. It is Platform 1.0 with one change: the agent chart moves to 2.6.17, pinning operator image d8475a8, which fixes the operator rewriting each workload Argo CD Application about 20 times a second. Platform 1.0 stays installable while it is in support. The catalog also carries Platform 0.9, the predecessor the upgrade path moves from — but the installer refuses it, because its agent chart (2.2.0) cannot create a cluster’s workload Applications, and 2.6.5 is the first agent chart that can. A version the CLI does not carry is refused by preflight. What each version contains is on the Bundle contents page.

Re-running the same command against the same cluster is safe. The installer converges: it does not duplicate resources and it does not fail because something is already present.

Re-running is a journal replay rather than a second install. preflight, register and verify always run; every stage the journal records as completed is skipped.

Provisioning the machines

kubenest platform install expects hosts to exist. It does not create them.

You bring the machines. Provision them however you already provision servers — your cloud console, your Terraform, your hardware. The installer takes it from there.

Machine provisioning through kubenest is not part of this release. If it arrives, it will be a separate command rather than a flag on install: provisioning and installing fail in different ways and are re-run under different circumstances, and a failed install must never re-run terraform apply. GCP and Azure are not planned.

The console and the fleet view

Every cluster registered to the control plane appears in the console’s fleet view with its bundle version, HA tier and health, so a cluster that is behind or unhealthy is visible rather than silent. See Console.

What the installer does, in order

Every install prints progress at the terminal, and every stage names itself in any failure.

The order is not arbitrary — every stage depends on the ones above it.

A registered install — thirteen stages

With the CLI logged in and no --control-plane flag, the install runs these thirteen stages:

Stage 1 writes nothing anywhere. Stage 2 writes only to the control plane. The first change to any of your machines happens at k3s-server.

A --control-plane install — fourteen stages

The first cluster adds the control-plane stage and moves register after it, because registering needs the control plane that stage has just installed. kubenest-agent follows register because it needs the credential register mints.

The diagram numbers the registered order. In a --control-plane install a control-plane stage runs between platform-day2 and register, as the table above shows.

Everything above the labelled edge is recoverable by walking away. That is the property the ordering exists to give you: the expensive checks happen while abandoning the install costs nothing.

The documented time budget is fifteen minutes. It is a budget for one single-server core shape, not a claim about a three-node or profiled install.

Preflight checks

Preflight is the whole reason a failed install is cheap. Everything here is checked on every node before the first byte is written anywhere, and any failure aborts before a machine is touched.

Verifying the install

The verify stage runs these automatically and reports the result. They are also the checks to run by hand when something looks wrong, and they are the acceptance criteria the release tests assert against a real cluster.

kubectl get nodes

kubectl get pods -A

When it fails

A failed install that says error is worse than no installer. Every failure reports three things: which stage, which component, and what to do next.

There is no automatic rollback. A failed stage stops the install and leaves completed stages in place. Automatic teardown would destroy the evidence needed to diagnose the failure, can itself fail and leave a worse state, and is more expensive than resuming.

What makes that safe is that a half-installed cluster is never an unexplained state:

• The installer keeps a journal. Each completed stage is recorded locally. Resume is deterministic — it reads the journal rather than relying on every component happening to be idempotent.
• Failure remains local and legible. The terminal names the failing stage and the completed work stays available for diagnosis.
• There are exactly two supported exits, and the failure message prints both.

To recover, either:

# Resume: fix what the error names, then re-run the identical command.
kubenest platform install ...   # skips completed stages, resumes at the failure

# Or start over: return the hosts to a known state.
kubenest platform uninstall --confirm

If preflight failed, nothing was written to any node and no cluster record exists. Fix the reported condition and re-run. This is the common case, and it is why preflight is thorough.

Uninstall

Enterprise buyers ask about the exit before they commit to the entry, so the exit is documented and tested rather than improvised.

kubenest platform uninstall --confirm

This removes k3s and every component the installer placed, and leaves the machines in a known state.

Uninstall never destroys data by default. Persistent volumes and their contents survive.

To remove them, pass --destroy-data as well. Even then, uninstall only removes the kubenest-vg volume group if the installer created it — recorded at install time. A volume group you created yourself is never removed, on either path.