Skip to main content

Kubernetes

The Kubernetes integration reads a self-hosted Kubernetes or OpenShift cluster through its API server. It runs on an Integrator that can reach the API server, so the cluster need not be exposed outside your network.

It is read-only. The service account can only get and list; the integration never creates, scales, patches or deletes anything.

What it collects​

SyncCollects
Cluster discoveryThe cluster with its version, and every node with its addresses, OS, kernel, kubelet version, CPU, memory and readiness
Workload discoveryNamespaces, deployments, statefulsets, daemonsets, jobs and cronjobs with their ready counts; pods with their addresses and node; containers with their state; the images containers run from
Service discoveryServices with their cluster and load balancer addresses, ports and the pods they route to; ingresses with their hosts and addresses; on OpenShift, routes with their host and TLS termination

Clusters appear under Compute > Kubernetes, next to those from every public cloud, and what runs inside a cluster is listed on its page. Load balancer services, ingresses and routes appear under Networking > Load Balancers, container images under Compute > Registries. An OpenShift cluster is recognised automatically.

Create a read-only service account​

The commands below need kubectl with cluster-admin access (oc on OpenShift).

  1. Create a namespace and a service account for the integration:

    kubectl create namespace inventory
    kubectl create serviceaccount inventory-reader -n inventory
  2. Grant it get and list on the resources the syncs read, and nothing else:

    kubectl apply -f - <<'YAML'
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
    name: inventory-reader
    rules:
    - apiGroups: [""]
    resources: [namespaces, nodes, pods, services]
    verbs: [get, list]
    - apiGroups: [apps]
    resources: [replicasets, deployments, statefulsets, daemonsets]
    verbs: [get, list]
    - apiGroups: [batch]
    resources: [jobs, cronjobs]
    verbs: [get, list]
    - apiGroups: [networking.k8s.io]
    resources: [ingresses]
    verbs: [get, list]
    - apiGroups: [route.openshift.io]
    resources: [routes]
    verbs: [get, list]
    YAML
    kubectl create clusterrolebinding inventory-reader \
    --clusterrole=inventory-reader --serviceaccount=inventory:inventory-reader

    The route.openshift.io rule is ignored on plain Kubernetes and can be left in.

  3. Issue a token. A bound token with a long duration is the simplest:

    kubectl create token inventory-reader -n inventory --duration=8760h

    The API server may cap the duration. For a token that does not expire, create a token secret instead and read it out:

    kubectl apply -f - <<'YAML'
    apiVersion: v1
    kind: Secret
    metadata:
    name: inventory-reader-token
    namespace: inventory
    annotations:
    kubernetes.io/service-account.name: inventory-reader
    type: kubernetes.io/service-account-token
    YAML
    kubectl get secret inventory-reader-token -n inventory -o jsonpath='{.data.token}' | base64 -d

A client certificate signed by the cluster CA, with the same ClusterRole bound to its subject, works in place of a token.

Connect it​

  1. Under Integrations, add Kubernetes with the API server URL (for example https://api.k8s.example.internal:6443, the server of your kubeconfig) and the token, or the client certificate and its private key.
  2. In the integration's settings, assign the Integrator that can reach the API server.
  3. Enable the syncs you want.

Most API servers serve a certificate from the cluster's own CA. The first connection records the certificate's fingerprint and later connections must present the same certificate. After rotating it, clear the pinned fingerprint in the integration's settings.

A token the cluster refuses fails the sync with an error. It does not report an empty cluster.