# Connect Kubernetes

> Apply a service account whose ClusterRole only gets, lists and watches, copy the API server's address, the cluster's CA and the token, and add the connection.

About 5 minutes, with kubectl, as a cluster admin. VizTopo reads the cluster's nodes, namespaces, Deployments, StatefulSets, DaemonSets, pods, Services, Ingresses and NetworkPolicies, and finds what's exposed or risky: privileged pods, Services open to the internet, namespaces with no network policy. It never reads Secrets and changes nothing in the cluster. It works the same on EKS, AKS, GKE, OKE, k3s and kubeadm clusters.

## 1. A service account that only reads

With kubectl signed in to the cluster as a cluster admin, apply this. It creates a `viztopo` namespace with a `viztopo-reader` service account, a ClusterRole that only gets, lists and watches what VizTopo reads, the binding between them, and a token for the service account.

kubectl:

```sh
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
  name: viztopo
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: viztopo-reader
  namespace: viztopo
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: viztopo-reader
rules:
  - apiGroups: [""]
    resources: ["nodes", "namespaces", "pods", "services"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments", "statefulsets", "daemonsets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses", "networkpolicies"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: viztopo-reader
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: viztopo-reader
subjects:
  - kind: ServiceAccount
    name: viztopo-reader
    namespace: viztopo
---
# A long-lived token for the service account (Kubernetes fills it in).
apiVersion: v1
kind: Secret
metadata:
  name: viztopo-reader-token
  namespace: viztopo
  annotations:
    kubernetes.io/service-account.name: viztopo-reader
type: kubernetes.io/service-account-token
EOF
```

> **Note:** The role names exactly what VizTopo reads, and no Secrets or ConfigMaps. Applying it again changes nothing that's already right, so it's also how to add a read VizTopo later asks for.

## 2. The address, the CA and the token

Each command prints one thing to paste into VizTopo: the API server's address, the cluster's CA certificate, and the service account's token.

The API server's address:

```sh
kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'
```

The cluster's CA certificate:

```sh
kubectl -n viztopo get secret viztopo-reader-token -o jsonpath='{.data.ca\.crt}' | base64 -d
```

The token:

```sh
kubectl -n viztopo get secret viztopo-reader-token -o jsonpath='{.data.token}' | base64 -d
```

> **Note:** On viztopo.com, VizTopo reaches the API server from the internet: for a managed cluster, its public endpoint, where you can allow only VizTopo's address. A self-hosted VizTopo can also reach clusters on its own network.

## 3. Add the connection

In VizTopo: **Connections → Add connection → Kubernetes**. Paste the address, the CA certificate (or `certificate-authority-data` from your kubeconfig) and the token. **Test connection** reaches the API server with its certificate checked, signs in, lists the namespaces and asks the API server what the token may do, then **Save**.

> **Note:** The **Permissions** page checks every read VizTopo needs, and warns if the token can do more than read: read Secrets, run commands in pods, or everything (cluster-admin).

## Questions

### Why a service account token?

It's Kubernetes' own way for a program to sign in, and works on every cluster, managed or not, without your cloud's sign-in. Its ClusterRole only reads, and deleting its token Secret (or the service account) revokes it at once.

### Does VizTopo keep the token?

Yes, encrypted with AES-256-GCM on the server, so it can keep reading. It's never sent back to your browser and never logged. VizTopo sends it only to the API server you entered, with its certificate checked, and never follows a redirect elsewhere.

### Do pods count as boxes?

No. Each node counts as one box, and a node that's also an EC2, Azure, Google Cloud or Oracle Cloud VM VizTopo already reads counts once. Pods, Services and everything else are free.

### Can VizTopo change my cluster?

No. The ClusterRole only gets, lists and watches, and VizTopo has no actions for Kubernetes.

---

Source: https://viztopo.com/docs/connect-kubernetes (updated 2026-10-25). Start free: https://viztopo.com/signup