README
¶
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-bootstrap-script/cmd/kubeaid-cli@latest
Prerequisites
- Docker — must be installed and running (KubeAid Core runs as a container)
- SSH agent —
ssh-agentwith your keys loaded (SSH_AUTH_SOCKmust be set)
Quick start
-
Generate sample config files for your cloud provider:
kubeaid-cli config generate <aws|azure|hetzner|bare-metal|local> -
Edit the generated
general.yamlandsecrets.yamlin the output directory. -
Bootstrap a cluster:
kubeaid-cli cluster bootstrap --configs-directory ./outputs/configs/<provider>/
Usage
kubeaid-cli [command] [flags]
Commands
| Command | Description |
|---|---|
config generate <provider> |
Generate sample general and secrets config files |
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 | — | — | Yes |
| Hetzner Bare Metal | Yes | — | — | Yes |
| Hetzner Hybrid | Yes | — | — | Yes |
| Bare Metal | Yes | — | — | Yes |
| Local (K3D) | Yes | — | — | — |
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.
Development
See docs/DEVELOPMENT.md for setup instructions.
Requirements
Building
# Build the CLI binary
make build-cli
# Build the KubeAid Core container image
make build-image
# Run linter
make lint
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kubeaid-cli
command
|
|
|
kubeaid-cli/login
Package login implements the `kubeaid-cli login` subcommand.
|
Package login implements the `kubeaid-cli login` subcommand. |
|
kubeaid-core
command
|
|
|
kubeaid-storagectl
command
|
|
|
e2e
|
|
|
prompt/promptrunner
command
testcmd is a minimal binary that only runs the interactive config prompt.
|
testcmd is a minimal binary that only runs the interactive config prompt. |
|
internal
|
|
|
termsetup
Package termsetup prevents lipgloss/termenv from sending OSC escape sequences to query the terminal's background color.
|
Package termsetup prevents lipgloss/termenv from sending OSC escape sequences to query the terminal's background color. |
|
pkg
|
|
|
cert
Package cert provides helpers for reading PEM-encoded X.509 certificates.
|
Package cert provides helpers for reading PEM-encoded X.509 certificates. |
|
klist
Package klist reads and merges cluster registry YAML files from a local klist clone.
|
Package klist reads and merges cluster registry YAML files from a local klist clone. |
|
netbird
Package netbird provides a small, read-only view of the local NetBird daemon's state.
|
Package netbird provides a small, read-only view of the local NetBird daemon's state. |
|
utils/giturl
Package giturl is a tiny, dependency-free predicate package for classifying Git remote URL forms (HTTP(s) vs SSH).
|
Package giturl is a tiny, dependency-free predicate package for classifying Git remote URL forms (HTTP(s) vs SSH). |
|
utils/randval
Package randval generates random secret values used across kubeaid-cli — alphanumeric passwords for OIDC client secrets and Keycloak admin credentials, plus base64-encoded byte keys for symmetric crypto (e.g.
|
Package randval generates random secret values used across kubeaid-cli — alphanumeric passwords for OIDC client secrets and Keycloak admin credentials, plus base64-encoded byte keys for symmetric crypto (e.g. |
|
tools
|
|
|
generators/cmd
command
|
|
Click to show internal directories.
Click to hide internal directories.