Skip to main content

Install WhaTap Operator

This guide explains how to install the WhaTap Operator in a Kubernetes environment and configure the WhatapAgent CR to start monitoring with WhaTap.

Prerequisites​

  • Kubernetes cluster (v1.19+)
  • Helm 3.2 or later
  • WhaTap account and license key
Note
  • The WhaTap agent is installed in the whatap-monitoring namespace. This namespace cannot be changed.
  • The collection server address and port must be reachable so that data can be sent (TCP Outbound). You can find the address and port on the Management > Agent installation screen of the WhaTap monitoring service.

Installation​

Follow the steps below to install the WhaTap Operator and create the WhatapAgent CR.

Tip

On the Management > Agent installation > Kubernetes screen of the WhaTap monitoring service, selecting Operator as the installation method generates the commands below along with a WhatapAgent CR file (whatap_operator.yaml). Choose the image version, container runtime, environment (GKE, OpenShift), and optional features (GPU monitoring, APM auto-installation, OpenMetrics collection) on the screen, and download the file with those settings applied. Use this document when you write the file yourself or edit a downloaded one.

  1. Install the WhaTap Operator

    • If you are installing the agent for the first time, run the following commands:
    helm repo add whatap https://whatap.github.io/helm/
    helm repo update
    kubectl create ns whatap-monitoring
    export WHATAP_HOST=<collector IP>
    export WHATAP_LICENSE=<license key>
    export WHATAP_PORT=<collector port>
    kubectl create secret generic whatap-credentials --namespace whatap-monitoring --from-literal WHATAP_LICENSE=$WHATAP_LICENSE --from-literal WHATAP_HOST=$WHATAP_HOST --from-literal WHATAP_PORT=$WHATAP_PORT
    helm install whatap-operator whatap/whatap-operator --namespace whatap-monitoring
    Tip

    Advanced configuration

    Image registry and pull secret

    If you use a private registry or need to adjust image tags or the pull policy, set the following values in values.yaml.

      image:
      repository: public.ecr.aws/whatap/whatap-operator
      tag: latest
      pullPolicy: Always

      # For private registry
      imagePullSecret:
      name: <your-registry-secret-name>

    Scheduling and priority options

    You can control scheduling constraints and priority for the operator Pod. The template renders only when a value is specified, which preserves compatibility with existing users.

      priorityClassName: ""   # Example: system-cluster-critical
      nodeName: ""            # When you need fixed scheduling on a specific node
      nodeSelector: {}        # Example: { kubernetes.io/os: linux }
      affinity: {}            # Standard K8s Affinity schema
      tolerations: []         # Standard K8s Toleration list
    • Example
      priorityClassName: "high-priority"
      nodeSelector:
        nodepool: system

      affinity:
        nodeAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: kubernetes.io/os
                    operator: In
                    values: ["linux"]

      tolerations:
        - key: "node-role.kubernetes.io/control-plane"
          effect: NoSchedule

    If you use a custom configuration instead of the default values.yaml, install the operator with the following commands.

    • If the namespace already exists

      helm install whatap-operator whatap/whatap-operator -n whatap-monitoring -f custom-values.yaml

    • If the namespace does not exist, create it automatically and install

      helm upgrade --install whatap-operator whatap/whatap-operator -n whatap-monitoring --create-namespace -f custom-values.yaml
    • If you were previously using the WhaTap Kubernetes agent, run the following commands to install the agent:
    kubectl delete ns whatap-monitoring
    kubectl delete clusterrole whatap
    kubectl delete clusterrolebinding whatap
    kubectl create ns whatap-monitoring
    kubectl create secret generic whatap-credentials --namespace whatap-monitoring --from-literal WHATAP_LICENSE=$WHATAP_LICENSE --from-literal WHATAP_HOST=$WHATAP_HOST --from-literal WHATAP_PORT=$WHATAP_PORT
    helm install whatap-operator whatap/whatap-operator --namespace whatap-monitoring
    Note

    If the previous WhaTap Kubernetes agent was installed via yaml files or Helm, a clean install is required. It is recommended to uninstall the existing Kubernetes agent before using the Operator.

    • The operator is deployed as a deployment. Run the following command to check if the operator is running:
    kubectl get pods -n whatap-monitoring | grep -i operator
    • The result should show the whatap-operator pod in Running status.

      whatap-operator-pod

  2. Create the WhatapAgent CR

    • Apply the whatap_operator.yaml file downloaded from the installation screen to create the WhatapAgent custom resource. If you wrote the CR file yourself, use that file name.
    kubectl apply -f whatap_operator.yaml
    • The WhatapAgent CR defines deployment and configuration for WhaTap agents. It supports setting up the Kubernetes agent, auto-installing APM, and collecting OpenMetrics via the Open Agent.

Minimal Configuration​

This is a minimal configuration that enables the WhaTap master and node agents for basic Kubernetes monitoring.

whatap_operator.yaml
apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
  namespace: whatap-monitoring
spec:
  features:
    k8sAgent:
      masterAgent:
        enabled: true
      nodeAgent:
        enabled: true
        runtime: containerd                                     # Container runtime on the node
        runtimeSocketPath: /var/run/containerd/containerd.sock   # Container runtime socket path
      gpuMonitoring:
        enabled: false

Set runtime and runtimeSocketPath to match the container runtime on your nodes. Selecting the container runtime on the installation screen applies the values below automatically.

Container runtimeruntimeruntimeSocketPath
containerd (default)containerd/var/run/containerd/containerd.sock
Docker Enginedocker/var/run/docker.sock
CRI-Ocrio/var/run/crio/crio.sock

In a GKE environment, add the following setting under k8sAgent.

    k8sAgent:
      gke:
        enabled: true

When installed with the minimal configuration, whatap-master-agent and whatap-node-agent are additionally deployed as shown below.

whatap-master-agent, whatap-node-agent

Note

When installing the WhaTap agent with the operator, refer to WhaTap CR configuration options for details on CR settings (resource constraints, tolerations, imagePullSecret).

Default Configuration​


apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
spec:
  features:
    ### Uncomment to enable APM auto-installation - 
    ### Automatically injects the APM agent into application Pods to enable performance monitoring.
    # apm:
    #   instrumentation:
    #     targets:
    #       - name: hello-world
    #         enabled: true
    #         language: "java"          # Supported languages: java, python, nodejs
    #         whatapApmVersions:
    #           java: "2.2.58"          # (Optional) Pin a specific APM agent version
    #         namespaceSelector:
    #           matchNames:
    #             - default             # Namespace containing the application to monitor
    #         podSelector:
    #           matchLabels:
    #             app: "hello-world"    # Label of the application Pod to monitor
    #         config:
    #           mode: default           # APM agent mode setting

    ### Uncomment to enable Kubernetes monitoring - 
    ### Enables monitoring of Kubernetes cluster, nodes, and containers.
    # k8sAgent:
    #   masterAgent:
    #     enabled: true                 # Enable master agent (cluster-level metric collection)
    #   nodeAgent:
    #     enabled: true                 # Enable node agent (node and container-level metrics)
    #     runtime: containerd           # Container runtime on the node (containerd, docker, crio)
    #     runtimeSocketPath: /var/run/containerd/containerd.sock   # Container runtime socket path

    ### Uncomment to enable GPU monitoring - 
    ### Enables NVIDIA GPU metrics collection.
    #   gpuMonitoring:
    #     enabled: true                 # Enable GPU monitoring (NVIDIA DCGM-EXPORTER is installed as a sidecar in the whatap-node-agent)

    ### Uncomment to enable OpenMetrics collection (Prometheus-compatible format) - 
    ### Collects metrics in Prometheus format.
    # openAgent:
    #     enabled: true                 # Enable OpenAgent
    #     targets:
    #       - targetName: kube-apiserver
    #         type: ServiceMonitor      # Target type: ServiceMonitor, PodMonitor, StaticEndpoints
    #         namespaceSelector:
    #           matchNames:
    #             - "default"           # Namespace from which to collect metrics
    #         selector:
    #           matchLabels:
    #             component: apiserver  # Labels of the service/Pod to monitor
    #             provider: kubernetes
    #         endpoints:
    #           - port: "https"         # Metric endpoint port
    #             path: "/metrics"      # Metric path
    #             interval: "30s"       # Scraping interval for this endpoint
    #             scheme: "https"       # HTTP scheme (http or https)
    #             tlsConfig:
    #               insecureSkipVerify: true  # Skip TLS certificate verification
        #         metricRelabelConfigs:
        #           - source_labels: ["__name__"]
        #             regex: "apiserver_request_total"  # Filter to collect specific metrics
        #             action: "keep"                    # Keep only matching metrics
Note

The Operator installation method does not support Istio sidecar injection settings. Use the Helm or YAML installation method if you need to configure an Istio environment. Control plane metrics such as kube-apiserver are collected through the OpenAgent configuration. For details, see OpenAgent configuration.

Example Configurations​

In addition to supporting Kubernetes agents, the WhaTap Operator also provides APM auto-installation and custom metric agent setup. Use the following examples to deploy various configurations.

GPU Monitoring​

Instead of installing the Kubernetes monitoring agent, you can deploy the DCGM-EXPORTER container as a sidecar to the WhaTap node agent Pod.
Without additional configuration, simply apply the yaml below to collect metrics that are displayed in the GPU dashboard.

Note

If you configured DCGM-EXPORTER manually instead of using the built-in sidecar in the node agent, refer to the OpenAgent Configuration to collect dcgm metrics.

GPU Monitoring Auto Setup​

GPU Monitoring Auto Setup
apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
spec:
  features:
    openAgent:
      enabled: true  # Enable OpenAgent
    k8sAgent:
      masterAgent:
        enabled: true
      nodeAgent:
        enabled: true
      gpuMonitoring:
        enabled: true  # Enable GPU monitoring

Note: During auto-installation, the Open Agent automatically detects and scrapes the DCGM Exporter.

GPU Node Toleration​

If your GPU node has taints, you must add toleration settings.

GPU Node Toleration
    apiVersion: monitoring.whatap.com/v2alpha1
    kind: WhatapAgent
    metadata:
      name: whatap
    spec:
      features:
        k8sAgent:
          nodeAgent:
            enabled: true
            tolerations:
              - key: "nvidia.com/gpu"
                operator: "Exists"
                effect: "NoSchedule"
              - key: "gpu"
                operator: "Exists"
                effect: "NoSchedule"
          gpuMonitoring:
            enabled: true

APM Auto Installation​

Automatically install APM in the Kubernetes cluster without enabling Kubernetes monitoring agents.

Note

For more details, refer to the APM Auto-Installation Guide.

APM Auto Installation
apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: hello-world
            enabled: true
            language: "java"
            whatapApmVersions:
              java: "2.2.58"
            namespaceSelector:
              matchNames:
                - default
            podSelector:
              matchLabels:
                app: "hello-world"
            config:
              mode: default

OpenAgent​

Configure only the OpenAgent component to collect Prometheus-style metrics, without enabling Kubernetes monitoring agents or APM instrumentation.

Note

For more details, refer to the OpenAgent Configuration.

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
spec:
  features:
    openAgent:
        enabled: true
        targets:
          - targetName: kube-apiserver
            type: ServiceMonitor
            namespaceSelector:
              matchNames:
                - "default"
            selector:
              matchLabels:
                component: apiserver
                provider: kubernetes
            endpoints:
            - port: "https"
              path: "/metrics"
              interval: "30s"
              scheme: "https"
              tlsConfig:
                insecureSkipVerify: true
              metricRelabelConfigs:
                - source_labels: ["__name__"]
                  regex: "apiserver_request_total"
                  action: "keep"

Using Kubernetes Monitoring and APM Together​

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: hello-world
            enabled: true
            language: "java"
            whatapApmVersions:
              java: "2.2.58"
            namespaceSelector:
              matchNames:
                - default
            podSelector:
              matchLabels:
                app: "hello-world"
            config:
              mode: default
    k8sAgent:
      masterAgent:
        enabled: true
      nodeAgent:
        enabled: true
    openAgent:
        enabled: true
        targets:
          - targetName: kube-apiserver
            type: ServiceMonitor
            namespaceSelector:
              matchNames:
                - "default"
            selector:
              matchLabels:
                component: apiserver
                provider: kubernetes
            endpoints:
            - port: "https"
              path: "/metrics"
              interval: "30s"
              scheme: "https"
              tlsConfig:
                insecureSkipVerify: true
              metricRelabelConfigs:
              - source_labels: ["__name__"]
                regex: "apiserver_request_total"
                action: "keep"
Last updated on