Skip to main content

Installation

This guide covers bootstrapping your KubeAid-managed Kubernetes cluster. The installation process is the same for all providers and the configuration files you prepared in the previous step contain all provider-specific details.

Before You Begin​

Ensure you have completed:

Make sure :

  • Docker is running locally
  • Your configuration files are in ~/.config/kubeaid-cli/<cluster>/configs/
  • Your secrets.yaml is backed up in your password store

Installing KubeAid CLI​

If you haven't already installed the KubeAid CLI, run the official install script:

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

It supports x86_64 and arm64 on Linux and macOS, and installs to /usr/local/bin (may prompt for sudo). Alternatively, download the right package manually from the releases page - see the sections below. For Linux users who prefer native package managers, see the Native Package Installation section.

Verify the installation:

kubeaid-cli version

Manual Installation (tar.gz Packages)​

You can also manually download the appropriate tar.gz package for your platform from the releases page.

Available tar.gz Packages​

PlatformArchitecturePackage Name
macOSARM64 (Apple Silicon)kubeaid-cli_Darwin_arm64.tar.gz
macOSx86_64 (Intel)kubeaid-cli_Darwin_x86_64.tar.gz
LinuxARM64kubeaid-cli_Linux_arm64.tar.gz
Linuxx86_64kubeaid-cli_Linux_x86_64.tar.gz

Installation Steps​

  1. Download the appropriate package for your platform:

    # Example for Linux x86_64
    wget https://github.com/Obmondo/kubeaid-cli/releases/latest/download/kubeaid-cli_Linux_x86_64.tar.gz

  2. Extract the archive:

    tar -xzf kubeaid-cli_<OS>_<ARCH>.tar.gz

  3. Move the binary to your PATH:

    sudo mv kubeaid-cli /usr/local/bin/
    sudo chmod +x /usr/local/bin/kubeaid-cli

  4. Verify the installation:

    kubeaid-cli version

Native Package Installation​

Native packages are available for Linux distributions in both amd64 and arm64 architectures:

FormatArchitecturePackage NameDistribution
.debamd64kubeaid-cli_v<VERSION>_linux_amd64.debDebian, Ubuntu
.debarm64kubeaid-cli_v<VERSION>_linux_arm64.debDebian, Ubuntu
.rpmamd64kubeaid-cli_v<VERSION>_linux_amd64.rpmRHEL, Fedora, CentOS
.rpmarm64kubeaid-cli_v<VERSION>_linux_arm64.rpmRHEL, Fedora, CentOS
.apkamd64kubeaid-cli_v<VERSION>_linux_amd64.apkAlpine Linux
.apkarm64kubeaid-cli_v<VERSION>_linux_arm64.apkAlpine Linux
.pkg.tar.zstamd64kubeaid-cli_v<VERSION>_linux_amd64.pkg.tar.zstArch Linux
.pkg.tar.zstarm64kubeaid-cli_v<VERSION>_linux_arm64.pkg.tar.zstArch Linux

Note: Replace <VERSION> with the actual version number (e.g., v0.17.1).

Installation Examples​

Debian/Ubuntu:

KUBEAID_CLI_VERSION=$(curl -s "https://api.github.com/repos/Obmondo/kubeaid-cli/releases/latest" | jq -r .tag_name)
CPU_ARCHITECTURE=$([ "$(uname -m)" = "x86_64" ] && echo "amd64" || echo "arm64")
wget "https://github.com/Obmondo/kubeaid-cli/releases/download/${KUBEAID_CLI_VERSION}/kubeaid-cli_${KUBEAID_CLI_VERSION}_linux_${CPU_ARCHITECTURE}.deb"
sudo dpkg -i kubeaid-cli_${KUBEAID_CLI_VERSION}_linux_${CPU_ARCHITECTURE}.deb

RHEL/Fedora/CentOS:

KUBEAID_CLI_VERSION=$(curl -s "https://api.github.com/repos/Obmondo/kubeaid-cli/releases/latest" | jq -r .tag_name)
CPU_ARCHITECTURE=$([ "$(uname -m)" = "x86_64" ] && echo "amd64" || echo "arm64")
wget "https://github.com/Obmondo/kubeaid-cli/releases/download/${KUBEAID_CLI_VERSION}/kubeaid-cli_${KUBEAID_CLI_VERSION}_linux_${CPU_ARCHITECTURE}.rpm"
sudo rpm -i kubeaid-cli_${KUBEAID_CLI_VERSION}_linux_${CPU_ARCHITECTURE}.rpm

Verifying Checksums​

Each release includes a checksums file (kubeaid-cli_<VERSION>_checksums.txt) for verifying download integrity:

KUBEAID_CLI_VERSION=$(curl -s "https://api.github.com/repos/Obmondo/kubeaid-cli/releases/latest" | jq -r .tag_name)
wget "https://github.com/Obmondo/kubeaid-cli/releases/download/${KUBEAID_CLI_VERSION}/kubeaid-cli_${KUBEAID_CLI_VERSION#v}_checksums.txt"
sha256sum -c kubeaid-cli_${KUBEAID_CLI_VERSION#v}_checksums.txt --ignore-missing

Bootstrap the Cluster​

Run the bootstrap command, pointing it at the configs you generated during pre-configuration:

kubeaid-cli cluster bootstrap

Your only saved cluster is picked automatically. Once several clusters have a saved config, pass --cluster-name <cluster> to say which one (running without it lists them). If you generated the config somewhere else, pass --configs-directory <path> instead — outputs then land in that directory too.

What Happens During Bootstrap​

The bootstrap process will:

  1. Create a local management cluster - A temporary K3D cluster for orchestration
  2. Provision infrastructure - Create cloud resources (for cloud providers) or configure SSH access (for bare metal)
  3. Initialize Kubernetes - Deploy the control plane and worker nodes
  4. Install core components - Deploy Cilium, ArgoCD, Sealed Secrets, and KubePrometheus
  5. Configure GitOps - Set up ArgoCD to sync with your kubeaid-config repository

Bootstrap Architecture (ClusterAPI)​

Note: For KubeOne (SSH-only bare metal), there is no management cluster. KubeOne connects directly to your servers via SSH.

Monitoring Progress​

  • Logs are streamed to your terminal in real-time
  • All logs are saved to ~/.config/kubeaid-cli/<cluster>/logs/ (one timestamped file per run) for later review
  • The process typically takes 10-30 minutes (depending on provider and cluster size)

Bootstrap Output​

Upon successful completion, the CLI prints a summary panel that ends with the exact export KUBECONFIG=... line for your platform and provider.

Access the Cluster​

Copy the export line from the bootstrap output (on Linux it looks like the one below) and verify access:

export KUBECONFIG=~/.config/kubeaid-cli/<cluster>/kubeconfigs/main.yaml
kubectl cluster-info

VPN-type clusters (cluster.type: vpn, with NetBird/Keycloak): after bootstrap the public kube-apiserver load balancer is disabled and API access moves to the NetBird mesh - the generic kubeconfig flow above doesn't apply. Follow the post-bootstrap operator guide instead.

Expected output:

Kubernetes control plane is running at https://<cluster-endpoint>:6443
CoreDNS is running at https://<cluster-endpoint>:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

Verify Nodes​

kubectl get nodes

All nodes should show Ready status.

Verify Core Components​

# Check all pods are running
kubectl get pods -A

# Check ArgoCD applications
kubectl get applications -n argocd

Troubleshooting​

Common Issues​

IssueCauseSolution
Bootstrap hangsNetwork issues or resource constraintsCheck logs in ~/.config/kubeaid-cli/<cluster>/logs/
Management cluster fails to createDocker not runningStart Docker and retry
Cloud resources fail to provisionInvalid credentialsVerify secrets.yaml credentials
SSH connection fails (bare metal)SSH key issuesVerify SSH key permissions and host connectivity
Nodes not joiningNetwork or firewall issuesCheck security groups/firewall rules

Viewing Logs​

# List bootstrap logs (one timestamped file per run)
ls ~/.config/kubeaid-cli/<cluster>/logs/

# Follow the latest log in real-time (if bootstrap is running)
tail -f "~/.config/kubeaid-cli/<cluster>/logs/$(ls -t ~/.config/kubeaid-cli/<cluster>/logs | head -1)"

Retry Bootstrap​

If bootstrap fails partway through, you can retry:

# Clean up partial state
kubeaid-cli cluster delete management --cluster-name <cluster>

# Retry bootstrap
kubeaid-cli cluster bootstrap --cluster-name <cluster>

Hardware Failures Found During Installation​

KubeAid checks every disk before it writes anything and refuses a server that fails, so the install is often the first time anyone has looked closely at those disks. Expect some servers to be rejected.

See Hetzner hardware failures for how to read a CheckDisk failure, when it is safe to accept a disk, and how to triage a server that installs and then never boots.

Provider-Specific Notes​

AWS​

The bootstrap creates:

  • VPC with public/private subnets
  • NAT Gateway for private subnet egress
  • Security groups for control plane and workers
  • EC2 instances for nodes
  • Elastic Load Balancer for API server

Azure​

The bootstrap creates:

  • Resource group for all resources
  • Virtual network with subnets
  • Network security groups
  • Virtual machines for nodes
  • Azure Load Balancer for API server

Hetzner​

HCloud​

  • Creates cloud servers for control plane and workers
  • Sets up private network for inter-node communication
  • Configures load balancer for API server

Bare Metal​

  • Connects to existing servers via SSH
  • Configures networking and disk layout
  • Does not create new infrastructure

Bare Metal (SSH-only)​

  • Connects to your servers via SSH
  • Installs Kubernetes components directly
  • No cloud resources created
  • You manage the server lifecycle

Local K3D​

  • Creates a K3D cluster in Docker
  • For testing only-not for production
  • No cluster upgrades or disaster recovery support

Next Steps​

Once your cluster is up and running:

  1. Post-Configuration - Access dashboards, verify setup, configure services