HYPHAby S33D
Documentation › Install the agent

Monitor Kubernetes

Two things to set up: the agent on each node for the system, and a single agent that reads the cluster API with a read-only account.

The nodes

Install the agent on each node as on any Linux server. It sees the node's system, processes, network and journal. HYPHA does not ship a DaemonSet yet: installing by package or script, or with your usual deployment tool (Ansible, cloud-init), is the intended way.

The cluster

A single agent per cluster reads the API: one on a control-plane node, or on a machine that reaches the API. It reads nodes, pods, deployments, statefulsets, daemonsets and warning events. It needs neither metrics-server nor any write permission.

1. Create the read-only account

apiVersion: v1
kind: Namespace
metadata:
  name: hypha
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: hypha-lecture
  namespace: hypha
automountServiceAccountToken: false
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: hypha-lecture
rules:
  - apiGroups: [""]
    resources: [nodes, pods, events, namespaces]
    verbs: [get, list, watch]
  - apiGroups: [apps]
    resources: [deployments, statefulsets, daemonsets, replicasets]
    verbs: [get, list, watch]
  - nonResourceURLs: [/version, /healthz, /readyz, /livez]
    verbs: [get]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: hypha-lecture
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: hypha-lecture
subjects:
  - kind: ServiceAccount
    name: hypha-lecture
    namespace: hypha
---
apiVersion: v1
kind: Secret
metadata:
  name: hypha-lecture-jeton
  namespace: hypha
  annotations:
    kubernetes.io/service-account.name: hypha-lecture
type: kubernetes.io/service-account-token

This role gives no access to secrets, configmaps, pod logs or exec. Check it:

kubectl auth can-i list pods -A --as=system:serviceaccount:hypha:hypha-lecture     # yes
kubectl auth can-i get secrets -A --as=system:serviceaccount:hypha:hypha-lecture   # no

2. Give the token to the agent

umask 077
kubectl -n hypha get secret hypha-lecture-jeton -o jsonpath='{.data.token}' | base64 -d | sudo tee /etc/hypha/kubernetes.token >/dev/null

3. Declare the cluster

/etc/hypha/conf.d/20-kubernetes.yaml:

integrations:
  kubernetes:
    enabled: true
    cluster: production            # kube_cluster tag
    url: https://api.k8s.example:6443
    token_file: /etc/hypha/kubernetes.token   # read again on every pass
    ca_file: /etc/kubernetes/pki/ca.crt

Then sudo hypha-agent check-config && sudo systemctl restart hypha-agent.

In a pod whose service account holds this role, the agent finds the API and the mounted token on its own, without url or token_file.

Several clusters: an instances list, one named entry per cluster (see Configuration).

What HYPHA collects

DataName
Nodes, ready nodeskubernetes.nodes, kubernetes.nodes.ready
Node ready, pressures, cordon (check)kubernetes.node
Running, pending, failed, unschedulable podskubernetes.pods.running, .pending, .failed, .unschedulable
Container restartskubernetes.containers.restarts
Workload available (check, pods in CrashLoopBackOff named)kubernetes.workload
Desired and available replicaskubernetes.workload.desired, .available
CPU and memory requests per nodekubernetes.node.cpu.requests_pct, kubernetes.node.mem.requests_pct
API reachablekubernetes.can_connect

On a kubeadm node, add /etc/kubernetes/pki/*.crt to the watched certificates (integrations.x509.paths): HYPHA warns you before their one-year expiry.

Monitor templates

The Kubernetes family of the catalogue: cluster unreachable, node unavailable, degraded workload, restarting containers, unschedulable pods.

Updated: 19 November 2026