Skip to main content

Install the Wakora agent on Kubernetes

On Kubernetes the agent runs as a DaemonSet: one instance per node, each registering as a host, plus the cluster view (nodes, pods, namespaces, crash loops, pending pods) read from the API server through a read-only ServiceAccount. Tested on k3s; the definitions also recognise RKE2 and k0s control planes.

Planned

A published container image is planned. Today you build the image yourself from the public source and push it to a registry your cluster can pull from; the manifest is ready and points at wakora/agent:latest, replace that with your image.

Build the image​

The Dockerfile in the public repository is four lines: a Debian slim base with ca-certificates and procps, plus the agent binary. Download the signed Linux binary (verify it as described in Install) into the build context and build:

git clone https://github.com/wakora-io/agent.git
cd agent/packaging
curl -fsSL https://get.wakora.io/bin/wakora -o wakora
docker build -t registry.example.com/wakora-agent:latest .
docker push registry.example.com/wakora-agent:latest

Deploy​

Create the namespace and the key secret, point the manifest at your image, apply:

kubectl create namespace wakora
kubectl -n wakora create secret generic wakora-key --from-literal=teamkey=<YOUR_TEAM_KEY>
sed -i 's#wakora/agent:latest#registry.example.com/wakora-agent:latest#' k8s-daemonset.yaml
kubectl apply -f k8s-daemonset.yaml

The manifest (packaging/k8s-daemonset.yaml) creates:

  • a ServiceAccount bound to a ClusterRole that can only get and list nodes, pods and namespaces plus the metrics.k8s.io API. No write verb, no secrets access, no cluster-admin.
  • a DaemonSet with hostPID and hostNetwork, so each agent sees its node's processes and ports, the SYS_PTRACE capability for the profiling layer of APM, and a seccomp RuntimeDefault profile.
  • an init container that runs wakora --key once with the team key mounted from the secret, so the long-running agent process never carries the key in its environment.
  • hostPath mounts for /etc/wakora and /var/lib/wakora on the node, which is where the node's identity and spool live.

Each node appears in the console as a host within a minute. The cluster metrics are collected by whichever agents run on a control-plane node, through the in-cluster ServiceAccount token; the definition also accepts a kubeconfig at the usual k3s, kubeadm and k0s paths when the agent runs on the node directly rather than in the DaemonSet.

Verify​

kubectl -n wakora get pods -o wide
kubectl -n wakora logs ds/wakora-agent -c agent --tail=50

The agent log ends its start-up with the same checklist wakora doctor prints.

Notes​

  • Do not share /etc/wakora between the DaemonSet and an agent installed directly on the node: the identity is sealed to the machine id, and a pod's machine id differs from the host's. Use the DaemonSet or the host install per node, not both.
  • Pod logs are collected only for problem pods (not Running, restarting, or in CrashLoopBackOff), never for the whole cluster. See Monitoring Kubernetes.
  • Containers other than the agent's own are excluded from host-level service discovery by their cgroups; the Docker probe covers Docker-managed containers, and Kubernetes pods are covered by the cluster view.

Next: Monitoring Kubernetes.