Skip to main content
KubeAid

Open-source Kubernetes platform: install and operate clusters the same way everywhere — with the ecosystem's churn handled for you.

Latest Release License: AGPL v3 Stars Contributors Issues Last Commit

Ask DeepWiki Release Build Chart Updates

Documentation · Getting Started · Why KubeAid? · Roadmap

Running Kubernetes means tracking a moving ecosystem: charts get deprecated, APIs break, defaults turn out to be security risks. KubeAid carries that overhead for you — a curated stack of 100+ vendored Helm charts with tested defaults, shipped as reviewed updates you pull when it suits you. Nothing is fetched live from upstream at deploy time: what you deploy is exactly what was reviewed. Runs everywhere: AWS and Azure (self-managed, or managed EKS/AKS), Hetzner, bare metal, or locally on K3D.

This repository holds the platform itself — curated Helm charts, monitoring, and secure defaults. It is consumed by the KubeAid CLI, which is the tool you actually run to create and manage clusters.

Table of Contents​

What Exactly Is KubeAid?​

Installing Kubernetes looks easy until you do it on a second platform. AWS wants IAM roles, Azure wants Workload Identity, Hetzner and bare metal have their own models — and that's before monitoring, ingress, storage, and upgrades. KubeAid removes the per-platform relearning: one workflow, one repository layout, one set of defaults, everywhere.

It is three pieces that work together:

  1. This repository (KubeAid) — the platform definition: an ever-expanding catalogue of 100+ maintained Helm chart wrappers in argocd-helm-charts/, with tested default values and automated weekly updates, plus kube-prometheus monitoring generated with Jsonnet. This makes KubeAid an application platform, not just an installer — each app is extended and integrated beyond its upstream chart:

    • Central operators manage common resources — databases (PostgreSQL, MariaDB, MongoDB), message queues (Kafka, RabbitMQ), Redis, backups — instead of per-app one-off setups.
    • Principle of least privilege — application-level network policies restrict apps to exactly the traffic they need.
    • Single sign-on — Keycloak SSO integration documented for supported apps.
    • Operational procedures — documented optimal configuration, backup and restore, and solutions to challenges already encountered.

    You don't run anything from here directly — it is consumed by the KubeAid CLI, and later by ArgoCD, straight from upstream by default. For production we recommend mirroring it into your own Git platform, so you keep full control even if access to the upstream repository is ever lost.

  2. KubeAid CLI — the entry point. A command-line tool you run once per cluster: it consumes this repository, generates your configuration, and bootstraps the cluster using Cluster API (or KubeOne for SSH-only bare metal).

  3. Your kubeaid-config repository — created from the sample template and filled in during bootstrap; holds all your cluster-specific settings, layered on top of the KubeAid platform defaults. ArgoCD inside the cluster watches it and applies changes, so Git is the single source of truth for everything running in the cluster.

Every KubeAid cluster ships with Cilium (kube-proxyless), ArgoCD, Sealed Secrets, and kube-prometheus. By default, auto-sync is not enabled, so you decide when changes are applied; you can turn it on per application if you prefer automated deployments.

How It Works​

You commit to your kubeaid-config repository, and ArgoCD inside the cluster continuously pulls charts from KubeAid and your values from kubeaid-config, reconciling the platform stack and your applications. The KubeAid CLI runs once to bootstrap: it writes your initial config, provisions the cluster, and pivots Cluster API into it:

KubeAid architecture diagram: the operator pushes to kubeaid-config; Argo CD in the cluster pulls charts from the KubeAid repo and values from kubeaid-config, applying the platform stack and your applications; the KubeAid CLI runs once to bootstrap and pivot Cluster API into the cluster

One rule to know up front: if you run a KubeAid mirror, never commit directly to its master/main branch — that branch is how updates are delivered to you, so keeping it clean means updating your cluster is as simple as a git pull.

Quick Start​

# Install the KubeAid CLI (x86_64/arm64, Linux and macOS)
curl -fsSL https://raw.githubusercontent.com/Obmondo/kubeaid-cli/main/scripts/install.sh | sh

# Interactive prompt walks you through cluster name, platform
# (local K3D, AWS, Azure, Hetzner, bare metal) and everything else
kubeaid-cli config generate

# Review the generated config, then bring the cluster up
kubeaid-cli cluster bootstrap --cluster-name <cluster>

Your answers land under ~/.config/kubeaid-cli/<cluster>/configs (use --configs-directory to choose another location). Other install methods (Nix, Homebrew, from source) are in the KubeAid CLI README.

Choosing local K3D gives you a playground on your own machine — the workflow is identical to a production cloud cluster. The Getting Started Guide walks through prerequisites, configuration, installation, and day-2 operations for every supported platform.

Features​

  • No-mental-overhead updates: we track what's broken, deprecated, or superseded across the whole stack, and ship tested chart and security updates weekly — ready to be applied to your clusters at will, so you can focus on your own applications.
  • Multi-cloud installation: self-managed clusters on AWS, Azure, Hetzner, and bare metal; managed control planes on EKS and AKS; hybrid Hetzner Bare Metal + HCloud clusters. One install method, any target.
  • GitOps everything: all cluster changes go through Git, and drift is detected if anyone changes resources directly in the cluster.
  • Curated application catalogue: an ever-growing list of open-source Kubernetes applications in argocd-helm-charts/, each wrapped with default values that follow current best practices. Upstream charts are vendored into this repository, so what you deploy is exactly what was reviewed — a defence against supply-chain attacks, backed by frequent security scans of all software used in the clusters.
  • Monitoring built in: advanced, customised Prometheus monitoring from a per-cluster config file, with automated handling of trivial alerts like disks filling up.
  • Secrets in Git, safely: sealed-secrets encrypts secrets locally before they are committed to your config repository.
  • Unified access management: cluster access runs over the NetBird mesh with Keycloak as the SSO identity provider by default. Teleport remains available as an optional, deprecated alternative.
  • Cluster security: NetworkPolicies enforce least privilege between applications and secure intra-cluster and ingress traffic.
  • Lifecycle operations: auto-scaling, backup and recovery, live migration of applications or whole clusters, major upgrades via a parallel shadow cluster, and air-gapped operation.
  • Compliance by default: security and operational defaults mapped to ISO 27001:2022, covering GDPR and NIS2 goals.

The implementation status of each feature is documented in Technical Details on the Features; planned work lives in the Roadmap.

Documentation​

You can find the documentation, guides and tutorials in the /docs directory.

Contributing​

Contributions are welcome — bug reports, chart updates, new providers, and documentation alike. See CONTRIBUTING.md for the workflow; note that commits need a DCO sign-off (git commit -s).

Community and Governance​

  • Code of Conduct — we follow the CNCF Community Code of Conduct.
  • Governance — how decisions are made and how maintainers are added.
  • Maintainers — current maintainers of the project.
  • Adopters — organizations running KubeAid; add yours with a PR.
  • Security policy — how to report vulnerabilities privately.

Support​

Community support happens through the issue tracker and the #kubeaid channel on Kubernetes Slack (get an invite there if you're not a member yet). Besides that, Obmondo (the primary developers of this project) offers professional support: we can observe your clusters, react to your alerts, and help you develop new features on clusters set up using this project.

There is zero vendor lock-in — KubeAid works the same with or without a support agreement, and any agreement can be cancelled at any time.

License​

KubeAid is licensed under the Affero GPLv3 license, as we believe this is the best way to protect against the patent attacks we see hurting the industry; where companies submit code that uses technology they have patented, and then turn and litigate companies that use the software.

The Affero GNU Public License has always been focused on ensuring everyone gets the same privileges, protecting against methods like TiVoization, which means it's very much aligned with the goals of this project, namely to allow everyone to work on a level playing ground.