NATS Is Out, the API Is In, and There’s a Doctor in the House
KubeClipper · release
Meet KubeClipper (and Meet the Doctor)
KubeClipper v1.7.0 just shipped, and it brought a stethoscope. The project’s brand-new kcctl doctor command diagnoses your entire platform — server, database, agents — in one pass. And underneath that shiny new tool, the team ripped out the old messaging plumbing and rebuilt the entire operation engine around the Kubernetes API itself. Same project, dramatically different guts.
Quick backstory for the uninitiated: KubeClipper is an open-source tool that installs and manages Kubernetes clusters for you. Not the containers inside them — the clusters themselves. Think of it as a general contractor for Kubernetes real estate: it pours the foundation, wires the electricity, and handles the maintenance, so you don’t have to babysit kubeadm — Kubernetes’ own manual installer — at 2 a.m.
It solves a very specific pain: installing and operating Kubernetes by hand is famously tedious. Certificate management, node registration, backups, upgrades — each one a rite of passage nobody asked for. KubeClipper automates that whole lifecycle. Teams running clusters on-premises or in air-gapped environments — networks with no internet access at all — use it because it speaks plain Kubernetes, not a proprietary cloud dialect.
So why care about v1.7.0 specifically? Two words: operational confidence. This release gives the platform a proper health-checkup tool, makes air-gapped installs far less fussy, and — the big one — rebuilds how every cluster operation flows through the system, using the same API patterns Kubernetes itself uses. v1.7.0 is the release where KubeClipper starts feeling like a platform you can trust on a bad day, not just a good one.
What’s New in v1.7.0
The Operation Engine Grows Up: API-Driven v2
Every cluster change in KubeClipper — creating a cluster, adding a node, rotating certificates — flows through an internal “operation engine.” In older versions, that engine leaned on NATS, a message-broker component embedded in the server, to shuttle tasks between the server and its agents. It worked, but it meant KubeClipper’s task delivery behaved like nothing else in your stack. Version 1.7.0 replaces the entire NATS-based path with Operation v2: operations now live in etcd — the same distributed key-value store Kubernetes itself uses as its database — and travel through the Kubernetes-style API with mTLS (mutually authenticated TLS, where both sides prove who they are). Agents watch for their work through the same list-and-watch pattern the Kubernetes API uses everywhere.
go test $(go list ./pkg/... | rg -v '/pkg/utils/systemctl$')That’s the validation command from the PR’s own checklist — and its companion line, “no NATS references remain in non-document source,” hints at the scale of the swap. (rg, by the way, is ripgrep, a fast code-search tool.) State transitions are now CAS-protected — compare-and-swap, the optimistic-locking trick that stops two writers from stomping each other — with built-in retry, cancel, and restart recovery. If the server reboots mid-operation, the system picks the work back up instead of leaving your cluster in a weird half-state. The PR’s validation log also records a full dress rehearsal on two real hosts: agent registration with per-agent certificates, cluster creation, backup and recovery, node add/remove, cancel and retry, and restart recovery.
If it walks like Kubernetes and quacks like Kubernetes, operators already know how to debug it.
One honest caveat, straight from the PR (#981): this is a clean break. Old agents, old operations, and NATS bridge mode are not supported. It is intended for fresh installations or re-registration of agent nodes. The rest of the changelog shows the team hardening v2 all cycle — status persistence with conflict retries, terminal access restored, and safety-boundary reads served from quorum storage.
kcctl status and kcctl doctor: X-Ray Vision for Your Platform
The other headliners are two new diagnostic commands. kcctl status is the quick pulse-check: it reports the health of kc-server, kc-etcd, and kc-agent in table, JSON, or YAML — with sane exit codes (0 healthy, 1 unhealthy, 2 for configuration, connection, or authentication errors), so it drops straight into your monitoring scripts. kcctl doctor is the deep checkup: it verifies local CLI access, kc-server subsystems, etcd health, agent heartbeats, systemd units (Linux service definitions), and connectivity — read-only, no repairs — and when something is wrong, it shows you evidence: sanitized journal logs and copy-paste manual troubleshooting commands.
Why should you care? Because “is it the network, the node, or me?” is the eternal question of platform operations. Doctor answers it with receipts.
kcctl status
kcctl doctorThat’s the whole invocation. No flags to memorize — doctor reads your existing ~/.kc/config and ~/.kc/deploy-config.yaml with no new configuration, and it goes deeper: it pulls deploy configuration from the API first and only falls back to the local cache when needed. Built across PR #977, PR #978, and PR #987, with a follow-up in #1017 that removes the etcdctl dependency (a separate etcd-inspection tool).
Air-Gapped Installs Get Real Registry Support
If you run clusters in environments with no internet, this one is for you. Previously, telling KubeClipper where to pull cluster images from meant the old image-repository and local-registry fields. Now Cluster.imageRegistry references a configured Registry resource by name — a named registry configuration you create once — and KubeClipper resolves the host, scheme, authentication, certificate authority, and skip-verify settings automatically, for every image type the platform pulls.
kcctl create cluster --image-registry <name>The team verified it by creating a real Kubernetes v1.36.1 cluster pulling from a local 127.0.0.1:5000 registry. Combined with offline local image loading (#985), air-gapped deployments stop being an arcane ritual. Note this is another deliberate break: the old image-repository fields and CLI aliases are gone (this resolves issue #973), and containerRuntime.registries remains the dedicated place for additional CRI — container runtime — registries. Shipped in PR #975.
Precheck Errors That Name Names
A small one, but the kind you appreciate at incident time: precheck failures now include the node IP and role (server or agent) in every error message, and errors from multiple nodes with the same problem are grouped together:
[role@ip]That little marker — literally [role@ip] in the error output — means no more grepping identical error blobs to figure out which of your forty nodes has the port conflict. Landed in PR #963, alongside #962, which adds a port-availability precheck before deployment in the first place.
Reliability Fixes Worth Knowing
Beyond the headliners, the release hardens the deploy path in ways existing users will feel:
- Etcd patience: deployments now wait for etcd health before proceeding (#988) instead of barreling ahead into a half-ready cluster.
- Configurable staging: the package staging directory is now configurable (#989), so small disks stop ruining your day.
- Failure details preserved: precheck failure details survive the trip to the UI (#990).
- Per-host transfer reporting: package transfers now report exactly which host failed (#995).
- Docs refresh: the documentation now lists the v1.7-supported Kubernetes versions (#1008) — worth checking before you plan an upgrade.
Should You Upgrade?
If you are an existing KubeClipper user on an older release, read this twice: the operation-engine swap is a one-way door — old agents, old operations, and NATS bridge mode are gone, and the intended path is a fresh install or agent re-registration. Plan the migration, don’t stumble into it. New deployment? v1.7.0 makes a strong case as your starting point — cleaner architecture, real diagnostics, and genuinely better air-gapped support.
KubeClipper is a CNCF sandbox project — sandbox is the early-stage tier of the Cloud Native Computing Foundation, the foundation that hosts Kubernetes — and it is clearly investing in the unglamorous operational foundations that make lifecycle tooling trustworthy.