Skip to main content

Cloud Providers

KubeAid provisions Kubernetes clusters on cloud providers using API-managed hosts. The cloud APIs automatically create, configure, and manage your infrastructure lifecycle.

Common Prerequisites​

All cloud providers require:

Install KubeAid CLI​

KUBEAID_CLI_VERSION=$(curl -s "https://api.github.com/repos/Obmondo/kubeaid-cli/releases/latest" | jq -r .tag_name)
OS=$([ "$(uname -s)" = "Linux" ] && echo "linux" || echo "darwin")
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}-${OS}-${CPU_ARCHITECTURE}"
sudo mv kubeaid-cli-${KUBEAID_CLI_VERSION}-${OS}-${CPU_ARCHITECTURE} /usr/local/bin/kubeaid-cli
sudo chmod +x /usr/local/bin/kubeaid-cli

AWS​

Provisions a KubeAid-managed Kubernetes cluster in AWS with:

AWS Prerequisites​

aws ec2 create-key-pair \
  --key-name kubeaid-demo \
  --query 'KeyMaterial' --output text --region <aws-region> > ./outputs/<cluster-name>.pem

AWS Setup​

# Generate configuration
kubeaid-cli config generate aws

# Edit outputs/configs/general.yaml and secrets.yaml

# Bootstrap the cluster
kubeaid-cli cluster bootstrap

# Access the cluster
export KUBECONFIG=./outputs/kubeconfigs/main.yaml
kubectl cluster-info

AWS Cleanup​

kubeaid-cli cluster delete main
kubeaid-cli cluster delete management

Azure​

Provisions a KubeAid-managed Kubernetes cluster in Azure with:

Azure Prerequisites​

  • Linux or MacOS with at least 16GB RAM (8GB may cause OOM issues)

  • Register a Service Principal in Microsoft Entra ID

  • OpenSSH keypair for VM access:

    ssh-keygen -t rsa -b 4096 -f azure-ssh-key

  • RSA key pair in PEM format for Azure Workload Identity:

    openssl genrsa -out jwt-signing-key.pem 2048
    openssl rsa -in jwt-signing-key.pem -pubout -out jwt-signing-pub.pem

Azure Setup​

# Generate configuration
kubeaid-cli config generate azure

# Edit outputs/configs/general.yaml and secrets.yaml

# Bootstrap the cluster
kubeaid-cli cluster bootstrap

# Access the cluster
export KUBECONFIG=./outputs/kubeconfigs/main.yaml
kubectl cluster-info

Azure Upgrade​

kubeaid-cli cluster upgrade --new-k8s-version v1.32.0
# Add --new-image-offer for OS upgrade

Azure Cleanup​

kubeaid-cli cluster delete main
kubeaid-cli cluster delete management

Hetzner​

Hetzner supports three deployment modes:

ModeControl PlaneWorkersAutoscaling
HCloudHCloud VMsHCloud VMs✅ Scale to/from 0
Bare MetalBare MetalBare Metal❌
HybridHCloud VMsHCloud + Bare Metal✅ (HCloud only)

All modes include:

HCloud Mode​

HCloud Prerequisites​

HCloud Setup​

kubeaid-cli config generate hetzner hcloud
# Edit outputs/configs/general.yaml and secrets.yaml
kubeaid-cli cluster bootstrap

Bare Metal Mode​

Bare Metal Prerequisites​

  • Create SSH KeyPair at https://robot.hetzner.com/key/index

    No 2 Hetzner Bare Metal SSH KeyPairs can have the same public key

  • If setting cloud.hetzner.bareMetal.wipeDisks: True, remove pre-existing RAID:

    wipefs -fa <partition-name>  # For each partition

Bare Metal Disk Layout​

For each server:

  • Level 1 SWRAID across specified disk WWNs
  • 25G LVG named vg0 with 10G root volume

Configure further via diskLayoutSetupCommands. Recommendations:

  • Allocate HDDs/SSDs to Ceph
  • Allocate NVMes to a ZPool (mirror mode) for ContainerD, logs, and OpenEBS ZFS LocalPV

Provider IDs: Bare-metal nodes use the canonical hrobot://<server-id> provider-ID format (enabled via the capi.syself.com/use-hrobot-provider-id-for-baremetal annotation on the HetznerCluster). This aligns CAPH's Machine providerID with the upstream Hetzner CCM robot provider.

Bare Metal Setup​

kubeaid-cli config generate hetzner bare-metal
# Edit outputs/configs/general.yaml and secrets.yaml
kubeaid-cli cluster bootstrap

Hybrid Mode​

Combines HCloud control plane with mixed HCloud + Bare Metal workers.

Hybrid Cloud Controller Manager (CCM) Architecture​

Hybrid clusters run two CCM instances from the same upstream chart, because the Hetzner CCM cannot enable its route controller (networking) and Robot bare-metal support at the same time:

CCM InstancePurposeScope
ccm-hcloudNetworking (HCLOUD_NETWORK), InternalIP assignment, LoadBalancers, routesHCloud nodes only
ccm-hetznerRobot provider-ID (hrobot://), node lifecycleBare-metal nodes only (controllers: cloud-node, cloud-node-lifecycle)

The HCloud CCM provides the InternalIP for the private-only control-plane nodes - without it, the apiserver cannot reach the kubelet and control-plane scale-up stalls on etcd health checks. The robot CCM is scoped to cloud-node + cloud-node-lifecycle only so it does not fight ccm-hcloud over LoadBalancers.

Pure HCloud or pure Bare Metal clusters use a single CCM instance.

Floating IPs on Control-Plane Nodes​

Control-plane nodes can bind HCloud Floating IPs via netplan for a stable public endpoint. The hcloud-fip-controller chart handles IP failover across nodes (leader-elected, ~15 s failover). The node-side IP binding (cloud-init/netplan) is the operator's responsibility.

Hybrid Prerequisites​

  • Both HCloud and Bare Metal SSH KeyPairs (see above)
  • Same disk wipe requirements as Bare Metal mode

Hybrid Setup​

kubeaid-cli config generate hetzner hybrid
# Edit outputs/configs/general.yaml and secrets.yaml
kubeaid-cli cluster bootstrap

Hetzner Cleanup​

All modes:

kubeaid-cli cluster delete main
kubeaid-cli cluster delete management

Common Operations​

Access Cluster​

export KUBECONFIG=./outputs/kubeconfigs/main.yaml
kubectl cluster-info

Logs are saved in outputs/.log. Access the ArgoCD and Grafana dashboards for monitoring.

See Also​