Frequently Asked Questions

Answers to common questions from engineers evaluating or operating KubeAid. For step-by-step setup, start with the Getting Started guide; for symptom-driven fixes, see Troubleshooting.

What is the difference between KubeAid, kubeaid-cli, and kubeaid-config?

Three pieces, three jobs. KubeAid (this repository) contains the curated Helm wrapper charts in argocd-helm-charts/ and templates - the software catalogue your clusters deploy from. kubeaid-config is your own repository holding cluster-specific configuration: values files, ArgoCD Application manifests, and sealed secrets, laid out per cluster under k8s/<cluster-name>/. kubeaid-cli is the command-line tool that generates configuration and bootstraps, upgrades, and deletes clusters. See Prerequisites for how the repositories relate and the Helm Umbrella Pattern for how they combine at runtime.

Do I need to mirror the KubeAid repository?

Not to get started - the only repository you must create is your own kubeaid-config (from the sample template); the platform repository is consumed from upstream by default. Mirroring KubeAid is recommended for production: your cluster's ArgoCD Applications then point at your mirror, so nothing lands on your cluster that you didn't pull into your own Git first, and updates only arrive when you update the mirror. Upstream charts are vendored into the repository, so what you deploy is exactly what was reviewed - a defence against supply-chain attacks. See Prerequisites.

Why can't I commit to my mirror's master branch?

The master/main branch of your KubeAid mirror is used to deliver updates from upstream - local commits there will conflict with incoming updates. All customization belongs in your kubeaid-config repository instead, which overrides chart values per cluster. See the warning in Prerequisites and the override mechanism in the Helm Umbrella Pattern.

How do updates reach my cluster?

Obmondo updates the upstream KubeAid repository with new application versions and improvements, published as release tags. Your ArgoCD Applications consume KubeAid either directly from the Obmondo repository or from your own fork, which you keep in sync with git fetch upstream --tags && git merge upstream/master. Either way, a new release changes nothing on the cluster by itself: every Application pins the KubeAid repository to a specific release tag (targetRevision). To roll an update out, bump that pinned tag across all apps with bin/update-kubeaid-argocd-app.sh -c <cluster-name> -r <tag> and push the resulting kubeaid-config change - only then does ArgoCD mark the affected applications OutOfSync, and you can inspect the exact diff before syncing during a service window. See Post-Configuration, Step 6 and Update KubeAid ArgoCD Apps.

Is auto-sync enabled - who actually applies changes?

ArgoCD continuously detects drift between Git and the cluster, but detection and application are separate steps. An Application only applies changes automatically if its syncPolicy.automated (optionally with selfHeal) is set - and selfHeal should be enabled carefully, since it reverts any manual change. The documented operational practice for KubeAid app updates is human-driven: review the diff, then selectively sync only the out-of-sync resources during a service window. See GitOps Drift Detection and the service window guide.

What clouds and managed control planes are supported?

Self-managed clusters on AWS, Azure, and Hetzner (HCloud, bare metal, and hybrid) via ClusterAPI; managed control planes on AWS EKS (via CAPA) and Azure AKS (via CAPZ); SSH-only bare metal via KubeOne; and local K3D for development. Autoscaling (including scale to/from zero) is available on the API-managed clouds. See the provider table in the Getting Started guide and the hosting reference.

How do I upgrade Kubernetes - and why is EKS/AKS different?

For self-managed clusters, edit cluster.k8sVersion in your general.yaml and run kubeaid-cli cluster upgrade; the CLI upgrades the cluster to the declared Kubernetes version and machine images. On EKS and AKS, cluster upgrade refuses to run because the control plane is owned by the cloud provider - instead you bump global.kubernetes.version in argocd-apps/values-capi-cluster.yaml in your kubeaid-config repo and let ArgoCD sync, after which CAPA/CAPZ upgrade the control plane and roll the node groups. See Basic Operations.

How are secrets handled?

With sealed-secrets: secrets are encrypted with the cluster controller's public key before being committed to your kubeaid-config repository, and only the controller running in the target cluster can decrypt them - so encrypted secrets are safe to store in Git. Note that the namespace is cryptographically bound at seal time, and you should back up the controller's keys so recreated clusters can decrypt existing sealed secrets. See Post-Configuration, Step 5 and the backup/restore procedure in the sealed-secrets README.

What monitoring comes built in?

Every KubeAid cluster ships with kube-prometheus: Prometheus for metrics, Alertmanager for alert routing, and Grafana for dashboards, configured per cluster via a Jsonnet variables file. Log monitoring is a separate, optional layer - one of OpenObserve, Graylog, or OpenSearch + Dashboards - running alongside the metrics stack. See Monitoring for the full picture.

Can KubeAid run air-gapped?

Partially, by design. The repository vendors everything needed to set up (or fully recover) a cluster - charts, templates, and configuration - and regular PVC backups are part of the model. For container images, the kyverno chart ships a harbor-proxy-cache-mutate ClusterPolicy that rewrites image references (docker.io, and optionally ghcr.io and registry.k8s.io) to your own Harbor registry at admission time, so workloads pull through your registry instead of the upstream ones - no per-chart image overrides needed. A fully disconnected install (every image pre-mirrored, with no upstream access at all) is still on the roadmap. See Features Technical Details.

What is a VPN-type cluster?

A cluster configured with cluster.type: vpn, which uses NetBird (with Keycloak) to put cluster access on a private mesh network. After bootstrap, the public kube-apiserver load balancer is disabled and API access moves to the NetBird mesh, so the generic kubeconfig flow doesn't apply - follow the post-bootstrap operator guide instead. The related keycloak, netbird, and acme secrets are described in Pre-Configuration.

Do I need Terraform or other infrastructure tooling?

No. kubeaid-cli bundles its tooling (K3D, Helm, clusterctl, KubeOne) as Go libraries, so you don't install Terraform, Terragrunt, or similar tools. Your workstation needs kubectl, jq, yq, Docker, and optionally cilium-cli (for cluster test) and WireGuard (for private cluster access). See Prerequisites.

Can I try KubeAid without a cloud account?

Yes - the local K3D deployment runs the whole stack in Docker on your machine at zero cost, using the same four-step flow as the cloud providers. It is for testing only: local K3D clusters don't support cluster upgrades or disaster recovery. See Prerequisites.

Where do I get help?

For general questions, bug reports, and feature requests, use GitHub Issues. For platform-level problems, check Troubleshooting first, and for bootstrap failures the kubeaid-cli troubleshooting guide. Professional support for KubeAid-managed clusters is available from Obmondo.