kubeaid-cli

KubeAid CLI

KubeAid CLI helps you operate KubeAid managed Kubernetes cluster lifecycle in a GitOps native way.

Architecture

KubeAid CLI is a thin client that proxies cluster and devenv commands to a containerized KubeAid Core engine. It pulls the matching ghcr.io/obmondo/kubeaid-core image, sets up Docker networking, mounts config files and SSH keys, and streams output back to your terminal.

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 (KubeAid Core runs as a container)
• SSH agent — ssh-agent with your keys loaded (SSH_AUTH_SOCK must be set)

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

Global flags

Cloud providers

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:

• docs/post-bootstrap.md — what to do right after a cluster comes up
• docs/add-bare-metal-worker.md — grow a Hetzner bare-metal worker pool (and the manual git-only flow)
• docs/upgrade-bare-metal.md — upgrade the Kubernetes version of a bare-metal (KubeOne) cluster

Identity and SSO:

• docs/keycloak-bootstrap.md — the managed Keycloak a VPN cluster bootstraps

Architecture and background:

• docs/architecture.md — how the CLI is put together
• docs/netbird-vpn-architecture.md — the NetBird mesh around the clusters
• docs/hetzner-hcloud-vpn-cluster.md — the HCloud VPN-cluster topology
• docs/bare-metal-provisioning.md — 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 CLI binary
make build

# Build the KubeAid Core container image
make build-image

# Run linter
make lint

License

GNU Affero General Public License v3.0