Clusters

Cluster Management (/clusters) is where platform administrators connect KubeOpera to the Kubernetes clusters it runs workloads on. There are three ways to add a cluster:

Option	Use it when…
Register This Cluster	You want KubeOpera to manage the cluster it is already running on. One click, nothing to enter.
Connect Existing	You already have a cluster (from any provider) and a kubeconfig for it.
Create New	You want KubeOpera to provision a brand-new cluster on AWS or GCP for you.

The Multi-Cluster view (/clusters/multi) then lets you compare every cluster side by side.

How cluster management works

Every cluster KubeOpera knows about has two representations:

• a record in kubeopera-api's database — what the dashboard lists and displays; and
• a HostCluster custom resource in the kubeopera-system namespace — the desired state that host-cluster-controller works to achieve.

When you add a cluster, kubeopera-api creates both. The controller then drives the cluster through a series of phases, and every time you open the page, kubeopera-api reads the resource's latest phase and message so the dashboard is always current.

apiVersion: kubeopera.io/v1alpha1
kind: HostCluster
metadata:
  name: 7e9d3a1b-...              # the cluster's ID
  namespace: kubeopera-system
spec:
  clusterID: "7e9d3a1b-..."
  mode: connect_existing           # connect_existing | provision_vanilla | provision_eks | provision_gke
  provider: aws
  region: eu-north-1
  connectKubeconfigSecretRef: hostcluster-7e9d3a1b-input-kubeconfig   # connect_existing only
  provisioning:                    # provision_* modes only
    topology: vanilla_kubeadm
    controlPlaneCount: 1           # vanilla only; more than 1 adds a load balancer
    nodeCount: 2
    instanceType: t3.medium
    kubernetesVersion: "1.31.0"
    credentialRef: <cloud credential ID>
  gitOpsRepoURL: https://github.com/acme/gitops-iac.git
  gitOpsPath: fluxcd/clusters/my-cluster
  gitCredentialsSecretRef: gitops-iac-credentials
  domain: my-cluster.acme.com
  registryPullSecretRef: hostcluster-7e9d3a1b-registry-pull   # optional: your own registry credential
  adminEmail: admin@acme.com       # optional: create a first administrator
  adminUsername: admin
status:
  phase: Ready
  kubeconfigSecret: hostcluster-7e9d3a1b-kubeconfig
  fluxHealthy: true
  adminPasswordSecretRef: hostcluster-7e9d3a1b-admin-password
  message: "Flux healthy and reconciling fluxcd/clusters/my-cluster. Administrator admin@acme.com created."

The phases

Phase	What happens
ValidatingAccess	The controller connects with the kubeconfig you supplied and confirms the API server responds. Temporary network errors are retried for up to five minutes.
Provisioning	cluster-provisioner creates the cloud infrastructure with Terraform (Create New only).
BootstrappingFlux	Flux is installed on the cluster and given credentials for your GitOps repository.
GeneratingGitOpsTree	gitops-scaffolder generates a complete environment for this cluster — ingress, certificates, storage, database, monitoring and every service — using the cluster's own domain, and commits it to Git.
InstallingKubeOpera	Flux is pointed at the new tree and reconciles it. If you provided administrator details, the first administrator account is created once the platform is up.
Ready	The cluster is managed by KubeOpera and kept in sync with Git.
Failed	Something went wrong; the message explains what and the controller retries where it can.

Whichever option you choose, every cluster ends up in the same place: running Flux, reconciling its own GitOps tree, and managed from the dashboard.

Your first cluster

A fresh KubeOpera installation has no host cluster yet, so /clusters shows a Get Started panel (and the main dashboard shows a banner pointing here). Choose:

• Register This Cluster for the fastest start, or
• Set Up Manually to open the Cluster Setup Wizard and connect or create a cluster.

Register This Cluster

If you're looking at the dashboard, KubeOpera is already running on some cluster. Register This Cluster adds that cluster using KubeOpera's own in-cluster service account — no kubeconfig or cloud credentials required. KubeOpera discovers:

• Nodes — how many there are and how many are ready;
• Kubernetes version — from the API server;
• Provider and region — from the nodes' cloud provider IDs (for example, aws:///eu-north-1a/i-0abc… → AWS, eu-north-1); clusters without a cloud integration show as unknown.

Registering is safe to repeat: KubeOpera identifies the cluster by the UID of its kube-system namespace, so clicking again returns the existing entry instead of creating a duplicate. The cluster KubeOpera runs on is marked as the host cluster; there is only ever one.

Connect an existing cluster

Use this for any cluster KubeOpera didn't create — an existing production cluster, a cluster from another provider, an on-premises cluster.

1. Open Clusters → New Cluster → Connect Existing.
2. Paste or upload a kubeconfig with cluster-admin access.
3. Enter a name, provider and region.
4. Optionally enter an administrator email and username to create a first admin account on this environment.
5. Select Connect.

KubeOpera checks the kubeconfig is valid before accepting it, then the cluster moves through ValidatingAccess → BootstrappingFlux → GeneratingGitOpsTree → InstallingKubeOpera → Ready. The kubeconfig is stored as a Kubernetes Secret, exactly as supplied.

Disconnecting or deleting

From the cluster's menu:

• Disconnect stops KubeOpera managing the cluster. It removes the HostCluster resource, the Flux sources KubeOpera created and the stored kubeconfig, but leaves everything running on the cluster untouched — use this when the cluster is still in use elsewhere.
• Delete (for clusters KubeOpera provisioned) tears down the cluster and its cloud infrastructure. You'll be asked to confirm by typing the cluster's name.

Create a new cluster

KubeOpera can provision a cluster on your cloud account and hand it straight to Flux.

1. Choose a provider and topology

Provider	Topology	What KubeOpera builds
AWS	Vanilla Kubernetes (kubeadm)	A VPC, one or more control-plane instances with stacked etcd, and a worker Auto Scaling Group. With more than one control-plane node, a Network Load Balancer fronts the API servers.
AWS	Managed (EKS)	A VPC, an EKS control plane operated by AWS, and a managed node group.
GCP	Managed (GKE)	A VPC network, a GKE control plane operated by Google, and a node pool.

Vanilla clusters bootstrap entirely from instance user data — no SSH is ever used. Control-plane nodes join one at a time, and kubeadm manages etcd membership, so multi-node control planes come up safely.

2. Choose a cloud credential

Provisioning needs access to your cloud account. Credentials are stored by auth-service, encrypted at rest, and visible only to platform administrators. After you save one, KubeOpera shows only its label and the last four characters — the secret is never sent back to the browser.

Supported credential types:

• Access key — an AWS access key ID and secret, or a GCP service-account key.
• Assume role — an AWS IAM role KubeOpera assumes for each provisioning run, so no long-lived keys are stored.

You can pick a saved credential or add one inline in the wizard.

3. Size the cluster

Choose the region, Kubernetes version, number and size of nodes, and — for vanilla clusters — the number of control-plane nodes. Add your domain and, optionally, an administrator email and username.

4. Submit and watch

The wizard closes as soon as you submit — provisioning takes anywhere from 10 to 40 minutes, and progress is shown on the cluster's card instead: a status badge plus a live message for the current phase.

Behind the scenes:

1. host-cluster-controller asks cluster-provisioner to start. It generates a Terraform configuration from your choices and runs it as a Kubernetes Job — one Job per cluster.
2. When the infrastructure is ready, cluster-provisioner retrieves a kubeconfig: from AWS SSM Parameter Store for vanilla clusters (published by the control plane once it has booted), or built from the cluster endpoint with short-lived cloud credentials for EKS and GKE.
3. The controller stores the kubeconfig and continues with BootstrappingFlux, exactly as for a connected cluster.

The controller tracks the provisioning job on the resource itself, so a controller restart mid-provision picks up where it left off.

Follow along from the command line

kubectl get hostcluster -n kubeopera-system -w
kubectl get jobs -n kubeopera-provisioning
kubectl logs -n kubeopera-provisioning job/provision-<cluster-id> -f

All Clusters

/clusters lists every cluster as a card with its health, node count, provider, region and Kubernetes version. The status badge shows:

• amber while a cluster is being set up (Pending, ValidatingAccess, Provisioning, BootstrappingFlux, GeneratingGitOpsTree, InstallingKubeOpera);
• green when it's Ready;
• red when it has Failed.

Open a card for per-node detail, current usage, cost and recent events.

How the health score is calculated

Every cluster's health score starts at 100 and loses points for each problem k8s-monitor finds:

Condition	Penalty
Each not-ready node	−5
Each node under memory pressure	−3
Each node under disk pressure	−4
Each node under PID pressure	−2
Each node with network unavailable	−6
Each failed pod	−2
Each crash-looping pod	−2.5
More than 10 restarting pods	−5
Control plane degraded	−30 (−15 if only the API server is affected)
Each unhealthy control-plane component	−8
Cluster CPU ≥ 95% (≥ 80%: −5)	−10
Cluster memory ≥ 95% (≥ 80%: −5)	−10

The score is kept between 0 and 100 and shown as green (80 and above), amber (60–79) or red (below 60).

Multi-Cluster view

/clusters/multi compares every managed cluster at once. kubeopera-api queries all clusters in parallel.

• Summary — total clusters, healthy clusters, ready nodes, average CPU usage and total monthly cost across the fleet.
• Comparison table — sortable by health, node readiness, CPU, memory and cost.
• Treemap — one tile per cluster, sized by CPU usage and colored by status. Hover a tile for details.

Use it to find the cluster that needs attention first, or to spot where capacity and cost are concentrated.

Next steps

• CloudSpaces — give teams their own virtual cluster on a host cluster.
• App Creation Flow — deploy your first application.
• Setup Guide — how an environment's GitOps tree is structured.