Skip to main content
Version: 2.0

Installation

In this tutorial you'll install KubeOpera on a Kubernetes cluster, sign in as the first administrator, and register the cluster so KubeOpera starts monitoring it.

Time: about 30 minutes · You'll need: a Kubernetes cluster and kubectl access to it.

Choose an installation method​

MethodBest forWhat it installs
GitOps with Flux (recommended)Real environments you'll keep running and upgrade.Everything: cluster add-ons (ingress, certificates, storage, monitoring, policy), databases, message bus and every KubeOpera service — all declared in Git and continuously reconciled.
Helm chartEvaluating KubeOpera on a cluster that already has an ingress controller and cert-manager.The KubeOpera CRDs and services.

Both methods produce the same platform. This tutorial follows the GitOps path and shows the Helm alternative at the end.

Prerequisites​

  • A Kubernetes cluster, version 1.29 or later, with at least 3 worker nodes of 4 vCPU / 16 GiB each. Need a cluster? See Setup: provision infrastructure.
  • kubectl, helm (3.14+) and the flux CLI (2.3+) installed locally.
  • A Git repository for your environment's configuration (GitHub or GitLab), and a token that can write to it.
  • A domain you control, for the dashboard and application addresses.

Step 1 — Generate your environment​

KubeOpera provides an environment template. Generate a new environment directory for your cluster:

git clone https://github.com/ochestra-tech/gitops-iac
cd gitops-iac
./tools/generate-gitops-env \
  --name my-env \
  --domain kubeopera.example.com \
  --region eu-west-1

This creates fluxcd/clusters/my-env/ containing:

  • infrastructure/ — cert-manager, ingress-nginx, external-dns, storage classes, monitoring, Kyverno, Falco and Sealed Secrets;
  • database/ — PostgreSQL;
  • apps/ — one entry per KubeOpera service, with hostnames under your domain;
  • freshly generated credentials, sealed so they are safe to commit.

Commit and push:

git add fluxcd/clusters/my-env
git commit -m "Add my-env environment"
git push

Step 2 — Install Flux and point it at your environment​

flux bootstrap github \
  --owner=<your-org> \
  --repository=gitops-iac \
  --path=fluxcd/clusters/my-env \
  --token-auth

Flux installs its controllers and begins reconciling everything under fluxcd/clusters/my-env. Add-ons come up first, then PostgreSQL and RabbitMQ, then every KubeOpera service.

Using GitLab?

Use flux bootstrap gitlab with the same flags. See the Flux bootstrap documentation for other Git providers.

Step 3 — Watch it come up​

flux get kustomizations --watch

Wait until every Kustomization shows Ready: True — usually 10–15 minutes. Then check the platform's pods:

kubectl get pods -n kubeopera-core
note

If a Kustomization stays not-ready, flux get kustomizations shows why. Most first-install issues are DNS or certificates — see Troubleshooting.

Step 4 — Create the first administrator​

Create your platform administrator account:

kubectl exec -n kubeopera-core deploy/authapi -- \
  kubeopera-admin create-super-admin \
  --email you@example.com \
  --username admin

The command prints a generated password. Keep it safe — you'll be asked to change it when you first sign in. You can run the same command later to reset a lost administrator password.

Step 5 — Sign in​

Open https://kubeopera.example.com (your domain from Step 1) and sign in with the administrator account.

No DNS yet? Forward the dashboard to your machine instead:

kubectl port-forward -n kubeopera-core svc/kubeopera-frontend 3000:80
# open http://localhost:3000

Step 6 — Register this cluster​

You'll land on the Dashboard with a Get Started banner. Select it, then Register This Cluster. KubeOpera discovers the cluster it's running on and starts collecting health, cost and telemetry — within a minute the Dashboard fills in.

🎉 KubeOpera is installed.

Alternative: install with Helm​

If your cluster already has an ingress controller (with an IngressClass), cert-manager (with a ClusterIssuer) and a default StorageClass, you can install KubeOpera with two charts:

helm repo add kubeopera https://charts.kubeopera.io
helm install kubeopera-crds kubeopera/kubeopera-crds
helm install kubeopera kubeopera/kubeopera \
  --namespace kubeopera-core --create-namespace \
  --set global.domain=kubeopera.example.com \
  --set global.ingress.className=nginx \
  --set global.ingress.clusterIssuer=letsencrypt-prod \
  --set global.adminBootstrap.email=you@example.com \
  --set global.adminBootstrap.username=admin

The chart generates every credential on first install (and never changes them on upgrade), and creates the administrator account for you. helm install prints how to retrieve the administrator's password. Then continue from Step 5.

Next steps​