Skip to main content

Kubernetes

Kubernetes is launch-scope, not deferred. The agent runs as a DaemonSet, one instance per node, and reports the cluster state read-only. For how to deploy it, see Installation and the DaemonSet manifest referenced there.

How the probe reads the cluster​

The k8s probe talks to the API server directly. It does not bundle client-go and it does not shell out to kubectl. Auth is preferred in this order:

  1. In-cluster ServiceAccount token (/var/run/secrets/kubernetes.io/serviceaccount), which is what the DaemonSet uses. The shipped manifest binds a read-only ServiceAccount with a ClusterRole that grants only get and list on nodes, pods, namespaces, and the metrics API. No cluster-admin.
  2. A kubeconfig (/etc/rancher/k3s/k3s.yaml, /etc/kubernetes/admin.conf, k0s, or an explicit path) when the agent runs on the host rather than in a pod.

If a kubeconfig has no CA, the probe fails closed rather than skipping server verification.

What it collects​

Read-only GETs to /version, /api/v1/nodes, /api/v1/pods, and the metrics API (metrics.k8s.io, which k3s ships by default) become:

  • Cluster: svc.k8s.nodes, svc.k8s.nodes_ready, svc.k8s.pods, and the phase split svc.k8s.pods_running, svc.k8s.pods_pending, svc.k8s.pods_failed, svc.k8s.pods_crashloop, plus svc.k8s.restarts_total and svc.k8s.namespaces.
  • Per namespace: svc.k8s.ns.pods, svc.k8s.ns.cpu_millicores, svc.k8s.ns.mem_bytes, tagged by namespace (capped at 50 namespaces).
  • Top pods: svc.k8s.pod.cpu_millicores and svc.k8s.pod.mem_bytes, tagged by namespace and pod (the top 20 by CPU).
  • Inventory: each namespace as a kind=namespace fact.

CPU quantities (n, u, m) and memory quantities (Ki, Mi, Gi, k, M, G) are parsed to millicores and bytes.

Matching​

The k8s definition matches the k3s-server process. It requires a recent agent version, so an older agent skips it with an honest log rather than failing.

Availability of the metrics API​

The per-namespace and per-pod CPU and memory numbers come from the metrics-server. If the cluster has no metrics-server, the cluster and pod-phase counts still work, only the resource usage numbers are absent.

Planned

A hands-off kubectl apply needs a container image registry, which is the remaining piece. The probe, the read-only RBAC, and the DaemonSet manifest are ready today. Group operations across nodes (the k8s operator) and matching non-k3s clusters (kubeadm) are on the roadmap.