KubeAid CLI

KubeAid CLI operates the full lifecycle of KubeAid-managed Kubernetes clusters — bootstrap, upgrade, recover, test, and delete — across AWS, Azure, Hetzner, and bare metal, the GitOps-native way.

Table of contents

• Architecture
• Features
• Installation
• Prerequisites
• Quick start
• Usage
• Cloud providers
• Kubernetes version support
• Configuration
• Documentation
• Development
• Contributing
• License

Architecture

KubeAid CLI is a single self-contained binary. The only local requirement is Docker, used to run a local K3D cluster.

How it provisions depends on the target:

• Cluster API clouds — AWS (CAPA), Azure (CAPZ + Crossplane), and Hetzner (CAPH): it stands up a throwaway K3D management cluster, installs Cluster API there, provisions your target cluster, then clusterctl move pivots every Cluster API resource onto the target so it self-manages and the K3D cluster is discarded.
• Generic bare metal — KubeOne installs Kubernetes straight onto your hosts, with no K3D or Cluster API.
• Local — the K3D cluster is simply the cluster itself.

From there it is GitOps. The engine renders your general.yaml into manifests and commits them to your own KubeAid Config repo that overrides only the genuine differences on top of the upstream KubeAid platform defaults; ArgoCD on the target then reconciles the addon stack — Cilium, cert-manager, kube-prometheus, Rook-Ceph, Velero, Sealed Secrets, and more. For the full breakdown, see docs/architecture.md.

Features

• Cluster lifecycle management — bootstrap, upgrade, recover, test, and delete Kubernetes clusters
• Development environments — spin up local K3D-based dev clusters
• Multi-cloud support — AWS, Azure, Hetzner (cloud, bare-metal, hybrid), and generic bare-metal
• GitOps native — integrates with ArgoCD, KubeAid Config repos, and sealed secrets
• Config generation — generate sample configuration files per cloud provider

Installation

Shell script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/Obmondo/kubeaid-cli/main/scripts/install.sh | sh

Supports x86_64 and arm64 on Linux and macOS. Installs to /usr/local/bin (may prompt for sudo).

Nix

nix profile install github:Obmondo/kubeaid-cli

Homebrew (macOS)

brew install Obmondo/kubeaid-cli/kubeaid-cli

From source

go install github.com/Obmondo/kubeaid-cli/cmd/kubeaid-cli@latest

Prerequisites

• Docker — must be installed and running (used to run the local K3D cluster)
• SSH access to your Git repos — either an ssh-agent with your key loaded, or an unencrypted private key file (privateKeyFilePath in general.yaml); use the agent for passphrased or YubiKey-backed keys

Quick start

1. Walk through the interactive prompt to generate general.yaml and secrets.yaml:

   kubeaid-cli config generate --configs-directory ./outputs/configs/<cluster>/

2. Review the generated files (the prompt covers everything required to bootstrap; hand-edit only when you want to override defaults).

3. Bootstrap the cluster:

   kubeaid-cli cluster bootstrap --configs-directory ./outputs/configs/<cluster>/

   cluster bootstrap fails fast if the configs are missing — run config generate first.

Usage

kubeaid-cli [command] [flags]

Commands

Command	Description
config generate	Interactively generate general.yaml and secrets.yaml via the config prompt
devenv create	Create a local development environment
cluster bootstrap	Bootstrap a new Kubernetes cluster
cluster upgrade <provider>	Upgrade an existing cluster
cluster recover <provider>	Recover a cluster
cluster test	Run tests against a cluster
cluster delete	Delete a provisioned cluster
version	Print version, commit, and build date

Global flags

Flag	Description
--debug	Enable debug logging
--configs-directory	Path to directory containing general.yaml and secrets.yaml

Cloud providers

Provider	Bootstrap	Upgrade	Recover	Delete
AWS	Yes	Yes	Yes	Yes
Azure	Yes	Yes	Yes	Yes
Hetzner Cloud	Yes	WIP	WIP	Yes
Hetzner Bare Metal	Yes	WIP	WIP	Yes
Hetzner Hybrid	Yes	WIP	WIP	Yes
Bare Metal	Yes	Yes	—	Yes
Local (K3D)	Yes	—	—	—

WIP — work in progress; landing soon, not yet generally available.

Kubernetes version support

Every Kubernetes version you request is validated at bootstrap. It must:

• start with v — for example v1.34.0;
• be a released version that is not past end-of-life — end-of-life is checked against endoflife.date data baked into the binary (refresh it with make fetch-k8s-eol);
• be within the range supported for your provider:

KubeAid CLI	AWS · Azure · Hetzner (Cluster API)	Bare metal (KubeOne)
v0.29.x	v1.30 → latest released (non-EOL)	v1.33 – v1.35

• Cluster API clouds — v1.30 up to the latest released minor.
• Bare metal — fixed to v1.33–v1.35 by KubeOne v1.13; the range moves when KubeOne is upgraded.
• KubePrometheus — matched to the Kubernetes version automatically, over v1.32–v1.36 (cgroup v1 support ends at v1.35).

Maintainers: update the table each release when the supported range, KubeOne version, or a pinned component changes.

Configuration

KubeAid CLI uses two YAML config files:

• general.yaml — cluster settings, cloud provider config, ArgoCD deploy keys, Git repo URLs, node groups, etc.
• secrets.yaml — cloud credentials, tokens, and other sensitive values.

See docs/config-reference.md for the full configuration reference.

Documentation

Day-to-day operator guides

• Post-bootstrap checklist — what to do right after a cluster comes up
• Add a bare-metal worker — grow a Hetzner bare-metal worker pool (see also the manual git-only flow)
• Upgrade a bare-metal cluster — bump the Kubernetes version of a bare-metal (KubeOne) cluster
• Troubleshooting — recovery paths for recurring bootstrap failures (Hetzner, Sealed Secrets, ArgoCD)

Identity and SSO

• Keycloak bootstrap — the managed Keycloak a VPN cluster bootstraps

Architecture and background

• Architecture — how the CLI is put together
• NetBird VPN architecture — the NetBird mesh around the clusters
• Hetzner HCloud VPN cluster — the HCloud VPN-cluster topology
• Bare-metal provisioning — how a Hetzner bare-metal node gets provisioned end to end

Development

See docs/DEVELOPMENT.md for setup instructions.

Requirements

• Nix and Direnv
• Docker

Building

# Build the kubeaid-cli binary
make build

# Build the kubeaid-storagectl binary (bare-metal storage helper)
make build-storagectl

# Lint and format
make lint
make format

# Run unit tests with coverage
make test

Run make help to list every target.

Contributing

Contributions are welcome.

1. Open an issue describing the bug or feature before starting substantial work.
2. Follow Google's Go style guide; run make lint and make format before pushing (CI is strict).
3. Write Conventional Commits — releases are cut with cocogitto.
4. Open a pull request that references the issue and explains the why, not just the what.

License

GNU Affero General Public License v3.0