Two ways to connect

Each cluster you connect is one source. Kubernetes is included from the Team plan, and in every self-hosted edition.

Connect a discovered cluster

When an AWS, Google Cloud or Azure account that is linked to a workspace syncs, Kumo.io records the EKS, GKE and AKS clusters it finds.

1. Open the workspace, go to its Connections tab and select Advanced.
2. Under Workspace Links, find Discovered Kubernetes Clusters. Each row shows the Cluster, its Cloud, Region and Endpoint.
3. Select Connect on the cluster.
4. Give the source a Display Name, and pick the cloud credential to use. Kumo.io preselects the source that discovered the cluster.
5. Select Connect cluster.

Kumo.io creates a Kubernetes source and starts its first sync.

The cloud identity behind that credential must be allowed into the cluster by the cluster's own access control:

• EKS: map the IAM role or user in the cluster's aws-auth configuration or an EKS access entry.
• GKE: grant the service account access through Google Cloud IAM.
• AKS: bind the service principal through Microsoft Entra ID.

If the workspace has no source for the cluster's cloud, Kumo.io asks you to connect that cloud account first, or to paste a kubeconfig instead. No clusters listed? They appear after an AWS, Google Cloud or Azure account linked to the workspace has synced.

Paste a kubeconfig

1. Open Cloud Connections and select Add a Source. (A discovered cluster's Paste kubeconfig link opens this form with the cluster already named.)
2. Under 1 · Choose a Provider, pick Kubernetes.
3. Paste the cluster's kubeconfig into Kubeconfig. Kumo.io uses its current-context.
4. In Cluster ARN, resource name, or name, identify the cluster. Prefer the managed cluster identifier: an EKS ARN, a GKE resource name or an AKS resource ID. It becomes the cluster's identity in Kumo.io and links the cluster to its cloud account. For EKS it also lets Kumo.io refresh the cluster token itself. A plain name works too.
5. Pick the Workspace (a Name is under Advanced Options), select Test Connection, then Connect Source.

On kumo.io, the kubeconfig must carry its credentials inline. Use a bearer token, or client-certificate-data with client-key-data, and give the cluster a server and certificate-authority-data. Kumo.io refuses kubeconfigs that run a command (exec plugins such as aws eks get-token), use an auth-provider, point at files on disk or set a proxy-url. For EKS, GKE and AKS, connecting a discovered cluster avoids this entirely. Self-hosted Kumo.io accepts these kubeconfigs, because it runs on your own infrastructure.

Network access

Kumo.io talks to the cluster's API server directly.

• kumo.io can only reach a cluster whose API endpoint is public. If the cluster limits which addresses may call it, allow Kumo.io's outbound address. A cluster with only a private endpoint needs a self-hosted Kumo.io running inside that network.
• Self-hosted Kumo.io reaches whatever its host can reach.

The discovered-clusters list shows each endpoint as public, private only, or both.

What Kumo.io needs inside the cluster

Kumo.io lists objects across all namespaces. It doesn't watch, change or exec into anything. The identity Kumo.io uses needs list on the kinds below, and get on namespaces.

Kumo.io has no official role manifest. This example ClusterRole grants exactly that:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kumo-reader
rules:
  - apiGroups: [""]
    resources: [pods, services, endpoints, nodes, namespaces, persistentvolumes,
                persistentvolumeclaims, configmaps, secrets, serviceaccounts, limitranges]
    verbs: [list]
  - apiGroups: [""]
    resources: [namespaces]
    verbs: [get]
  - apiGroups: [apps]
    resources: [deployments, replicasets, statefulsets, daemonsets]
    verbs: [list]
  - apiGroups: [batch]
    resources: [jobs, cronjobs]
    verbs: [list]
  - apiGroups: [autoscaling]
    resources: [horizontalpodautoscalers]
    verbs: [list]
  - apiGroups: [networking.k8s.io]
    resources: [ingresses, ingressclasses, networkpolicies]
    verbs: [list]
  - apiGroups: [discovery.k8s.io]
    resources: [endpointslices]
    verbs: [list]
  - apiGroups: [policy]
    resources: [poddisruptionbudgets]
    verbs: [list]
  - apiGroups: [storage.k8s.io]
    resources: [storageclasses]
    verbs: [list]
  - apiGroups: [rbac.authorization.k8s.io]
    resources: [roles, rolebindings, clusterroles, clusterrolebindings]
    verbs: [list]

Bind it to Kumo.io's identity with a ClusterRoleBinding.

Kumo.io keeps only the metadata of Secrets. It never stores secret values. If you'd rather not grant list on secrets, leave them out: Kumo.io marks that one kind as incomplete and syncs everything else. The same applies to any kind you leave out. The built-in view ClusterRole covers most kinds, but not Secrets, RBAC objects, or the cluster-wide Nodes, PersistentVolumes, StorageClasses and IngressClasses.

What Kumo.io reads

Kumo.io reads 28 Kubernetes kinds, plus the cluster itself:

• Workloads: Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob, HorizontalPodAutoscaler.
• Networking: Service, Endpoints, EndpointSlice, Ingress, IngressClass, NetworkPolicy.
• Storage and config: PersistentVolume, PersistentVolumeClaim, StorageClass, ConfigMap, Secret (metadata only).
• Availability: PodDisruptionBudget.
• Access: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding.
• Cluster: Node, Namespace, LimitRange.

Pods that have finished or are terminating are left out. See Kubernetes coverage for details. Once a cluster has synced, the Kubernetes service map diagram is available for environments that contain workloads.

Connect from the CLI

kumo source connect runs the same flow as Add a Source. The CLI reads one line from standard input, so convert the kubeconfig to single-line JSON first:

kubectl config view --minify --flatten -o json | jq -c . | \
  kumo source connect --provider kubernetes --credential-kind kubernetes.kubeconfig \
    --display-name staging --secret-material-stdin \
    --scope arn:aws:eks:eu-west-1:123456789012:cluster/staging

--minify --flatten keeps only the current context and inlines its certificates. --scope is the cluster identity, as in the form above. Add --no-sync to skip the first sync.

To check a cluster connection from the CLI:

kumo credential health check --source <source-id>

See the CLI reference for every flag.

If the connection fails