Skip to content

Kubernetes agent

The Zenoss agent for Kubernetes is a monitoring daemon that collects key cluster metrics from kube-apiserver and streams them directly to Zenoss Cloud. The agent sends both metric and model data for pods, containers, nodes, namespaces, and the cluster itself. The metric data can be viewed in dashboards or in Smart View; a Kubernetes dashboard template is available. The model data includes dependency relationships, which enable Smart View analyses of related cluster entities.

The Zenoss agent for Kubernetes supports Kubernetes 1.10 through 1.16 and requires metrics-server. You include the agent in a cluster with a deployment and Kubernetes schedules the agent in its own pod, on one node. The size of a cluster determines how much RAM the agent consumes; in small clusters, it consumes approximately 15MB. The agent uses incremental change notifications to collect data, rather than a polling interval, and so receives updates any time a monitored property changes. The agent sends a batch of metric data to Zenoss Cloud every 60 seconds and sends a batch of model data when the model data changes. The source code of the agent is public and an image containing its binary is available on Docker Hub.

Kubernetes data

Zenoss Cloud uses the data collected by the Zenoss agent for Kubernetes to create separate entities for each unique node, pod, container, and namespace in a cluster, and one entity for the cluster itself. To find a cluster in a dashboard scope query or Smart View query, enter the cluster name that you specified when you deployed the agent.

Entity relationships

The model data that the Zenoss agent for Kubernetes sends to Zenoss Cloud includes entity relationships. The following diagram illustrates the relationships:

The arrows show which objects affect other objects. The relationships are used to populate the related entities area in Smart View.

The following list replicates the diagram in text:

  • Nodes affect pods and the cluster.
  • The cluster affects namespaces.
  • Namespaces and containers affect pods.

Metric data

All of the metrics that the Zenoss agent for Kubernetes sends to Zenoss Cloud are gauges.

Metric Units
k8s.cluster.nodes.total integer
k8s.cluster.pods.total integer
k8s.cluster.containers.total integer
k8s.cluster.cpu.ms millisecond
k8s.cluster.memory.bytes byte

The value is the sum of the same metrics for all containers in the cluster.

Metric Units
k8s.node.cpu.ms millisecond
k8s.node.memory.bytes byte
Metric Units
k8s.namespace.pods.total integer
k8s.namespace.containers.total integer
k8s.namespace.cpu.ms millisecond
k8s.namespace.memory.bytes byte

The value is the sum of the same metrics for all containers in the namespace.

Metric Units
k8s.pod.containers.total integer
k8s.pod.cpu.ms millisecond
k8s.pod.memory.bytes byte

The value is the sum of the same metrics for all containers in the pod.

Metric Units
k8s.container.cpu.ms millisecond
k8s.container.memory.bytes byte

Deploying the Kubernetes agent

You can use any method you prefer to deploy the Zenoss agent for Kubernetes into a cluster. The following sections demonstrate using the kubectl command and using a Helm chart. Both methods require only the name of the cluster and an authentication key.

Deploying with kubectl

Use the sections on this page to deploy and manage Zenoss agent for Kubernetes with kubectl. The Zenoss agent for Kubernetes supports Kubernetes 1.8 and all subsequent versions and requires metrics-server.

Deploy the agent

To perform this procedure, you need an authentication key. Also, the deployment configuration in this procedure assumes that Kubernetes can download images from Docker Hub. If not, download the Zenoss agent for Kubernetes and add it to your local registry.

  1. Configure kubectl to use the correct context.

    kubectl config current-context
    
  2. Optional: Create a secret for the authentication key you are using for the cluster.

    While not required, creating a secret is the most secure way to manage information like authentication keys. Replace MY_API_KEY key with an authentication key:

    kubectl -n kube-system create secret generic zenoss \
      --from-literal=api-key=MY_API_KEY ; history -d $(history 1)
    

    The history command removes the authentication key from your shell history file.

  3. Create a configuration file for the agent.

    Replace MY_CLUSTER_NAME on line 60 with the unique name of the target cluster.

    zenoss-agent-kubernetes.yml
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: zenoss-agent-kubernetes
      namespace: kube-system
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      labels:
        kubernetes.io/bootstrapping: rbac-defaults
      name: system:zenoss-agent-kubernetes 
    rules:
    - apiGroups: ["metrics.k8s.io"]
      resources: ["nodes", "pods"]
      verbs: ["get", "list", "watch"]
    - apiGroups: [""]
      resources: ["nodes", "namespaces", "pods"]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["extensions", "apps"]
      resources: ["deployments"]
      verbs: ["get", "list", "watch"]
    ---
    apiVersion: rbac.authorization.k8s.io/v1beta1
    kind: ClusterRoleBinding
    metadata:
      name: zenoss-agent-kubernetes
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: system:zenoss-agent-kubernetes
    subjects:
    - kind: ServiceAccount
      name: zenoss-agent-kubernetes
      namespace: kube-system
    ---
    apiVersion: app/v1
    kind: Deployment
    metadata:
      name: zenoss-agent-kubernetes
      namespace: kube-system
      labels:
        app: zenoss-agent-kubernetes
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: zenoss-agent-kubernetes
      template:
        metadata:
          labels:
            task: zenoss-agent-kubernetes
        spec:
          serviceAccountName: zenoss-agent-kubernetes
          containers:
          - name: zenoss-agent-kubernetes
            image: zenoss/zenoss-agent-kubernetes
            env:
            - name: CLUSTER_NAME
              value: MY_CLUSTER_NAME
            - name: ZENOSS_API_KEY
              valueFrom:
                secretKeyRef:
                  name: zenoss
                  key: api-key
    
  4. Apply the deployment.

    kubectl apply -f zenoss-agent-kubernetes.yml
    

Manage the agent

To update the agent, edit its configuration file and then apply the file. Kubernetes applies only the changes.

kubectl apply -f zenoss-agent-kubernetes.yml

To remove the agent and all of its resource, enter the following command:

kubectl delete -f zenoss-agent-kubernetes.yml

Deploying with a Helm chart

Use this procedure to deploy Zenoss agent for Kubernetes with Helm. The Zenoss agent for Kubernetes supports Kubernetes 1.8 and all subsequent versions and requires metrics-server.

To perform this procedure, you need:

Follow these steps:

  1. Add the Zenoss repository that contains the Helm chart for the Zenoss agent for Kubernetes to Helm.

    helm repo add zenoss https://zenoss.github.io/charts/
    
  2. Optional: Review the chart parameters that you can specify during deployment.

  3. Deploy the agent.

    Replace MY_CLUSTER_NAME with the unique name of the target cluster, and replace MY_API_KEY with an authentication key:

    helm install zenoss/zenoss-agent-kubernetes \
      --set zenoss.clusterName=MY_CLUSTER_NAME \
      --set zenoss.apiKey=MY_API_KEY ; \
      history -d $(history 1)
    

    The history command removes the authentication key from your shell history file.

For more information about using Helm, refer to the Helm documentation.