Getting Started
This section gets you from zero to a running application on a Kubernetes cluster. If you have about 15 minutes and a cluster you can install Helm charts on, you can have kubenest managing your first app before you finish your coffee.
Who this is for
Getting Started is aimed at platform engineers and DevOps practitioners who are setting up kubenest for the first time — either for their own team or for an organization. You should be comfortable with Kubernetes basics (namespaces, pods, Helm) but you do not need to know kubenest’s internals yet. The Concepts section covers those once you have something running.
Prerequisites
Before you begin, make sure you have:
- A Kubernetes cluster — any distribution works (EKS, GKE, AKS, k3s, kind, RKE2). The cluster needs to be reachable from the hub’s WebSocket endpoint, but does not need to expose any inbound port for kubenest specifically; the operator connects outbound.
- Helm 3.x installed locally and configured to reach the cluster (
helm versionshould succeed). - ArgoCD installed on the cluster. kubenest’s operator uses ArgoCD as its GitOps engine. If ArgoCD is not present, the kubenest Helm chart can install a minimal instance for you (set
argocd.enabled=true). - A Git repository accessible from the cluster (GitHub, GitLab, self-hosted Gitea). The operator commits Helm values to this repo; ArgoCD reconciles from it.
- The kubenest backend and hub running and reachable. For production, these are deployed as a separate Helm release to a “control plane” cluster. For evaluation, they can run locally via Docker Compose (see the backend README).
kubenest is a self-hosted platform. There is no SaaS service to sign up for. You are responsible for running the backend, hub, and database infrastructure. The getting started guides assume you already have the backend and hub running and reachable.
The three-step path
Install kubenest on your cluster
The operator is installed via the kubenesthq/kubenest-helm Helm chart. This chart bundles the operator (Go controller), the hub connection configuration, and optional ArgoCD. You’ll need a cluster JWT (issued when you register the cluster in the backend) and the hub’s WebSocket URL.
Create a project
A project is a Kubernetes namespace plus kubenest’s metadata layer (quotas, RBAC role bindings, audit trail). Create one via the UI’s “New Project” wizard or via POST /api/v1/projects. Everything you deploy lives inside a project.
Deploy your first app
With a project in place, post an App spec to /api/v1/apps. The backend validates your component definitions, sends a StackDeploy create event through the hub to the operator, and the operator begins reconciling. Within seconds you can watch the phase transition from Pending → Deploying → Running in real time.