The Kubernetes integration is used to create a near real-time synchronization of topology and associated internal services from a Kubernetes cluster to StackState. This StackPack allows monitoring of the following:

  • Workloads

  • Nodes, pods, containers and services

  • Configmaps, secrets and volumes

Data flow

The Kubernetes integration collects topology data in a Kubernetes cluster as well as metrics and events.

  • StackState Agent V2 is deployed as a DaemonSet with one instance on each node in the Kubernetes cluster:

    • Host information is retrieved from the Kubernetes API.

    • Container information is collected from the Docker daemon.

    • Metrics are retrieved from kubelet running on the node and also from kube-state-metrics if this is deployed on the same node.

  • StackState Cluster Agent is deployed as a Deployment. There is one instance for the entire Kubernetes cluster:

    • Topology and events data for all resources in the cluster are retrieved from the Kubernetes API

    • Control plane metrics are retrieved from the Kubernetes API

  • Retrieved data is pushed to StackState via the Agent StackPack (StackState Agent V2) and the Kubernetes StackPack (StackState Cluster Agent).

  • In StackState:

    • ​Topology data is translated into components and relations.

    • ​Tags defined in Kubernetes are added to components and relations in StackState.

    • Relevant metrics data is mapped to associated components and relations in StackState. All retrieved metrics data is stored and accessible within StackState.

    • ​Events are available in the StackState Events Perspective and listed in the details pane of the StackState UI.



The following prerequisites are required to install the Kubernetes StackPack and deploy the StackState Agent and Cluster Agent:

  • A Kubernetes Cluster must be up and running.

  • A recent version of Helm 3.

  • A user with permissions to create privileged pods, ClusterRoles and ClusterRoleBindings:

    • ClusterRole and ClusterRoleBinding are needed to grant StackState Agents permissions to access the Kubernetes API.

    • StackState Agents need to run in a privileged pod to be able to gather information on network connections and host information.


Install the Kubernetes StackPack from the StackState UI StackPacks > Integrations screen. You will need to provide the following parameters:

  • Kubernetes Cluster Name - A name to identify the cluster. This does not need to match the cluster name used in kubeconfig, however, that is usually a good candidate for a unique name.

If the Agent StackPack is not already installed, this will be automatically installed together with the Kubernetes StackPack. This is required to work with the StackState Agent, which will need to be deployed on each node in the Kubernetes cluster.

Deploy the StackState Agent and Cluster Agent

For the Kubernetes integration to retrieve topology, events and metrics data, you will need to have the following installed on your Kubernetes cluster:

  • A StackState Agent on each node in the cluster

  • StackState Cluster Agent on one node

  • kube-state-metrics

These can be installed together using the Cluster Agent Helm Chart:

  1. If you do not already have it, you will need to add the StackState helm repository to the local helm client:

    helm repo add stackstate https://helm.stackstate.io
    helm repo update
  2. Deploy the StackState Agent, Cluster Agent and kube-state-metrics with the helm install command provided in the StackState UI after you have installed the StackPack.


In addition to the variables included in the provided helm command, it is also recommended to provide a stackstate.cluster.authToken. This is an optional variable, however, if not provided a new, random value will be generated each time a helm upgrade is performed. This could leave some pods in the cluster with an incorrect configuration.

For example:

helm install \
--namespace stackstate \
--create-namespace \
--set-string 'stackstate.apiKey'='<your-api-key>' \
--set-string 'stackstate.cluster.name'='<your-cluster-name>' \
--set-string 'stackstate.cluster.authToken'='<your-cluster-token>' \
--set-string 'stackstate.url'='<your-stackstate-url>' \
stackstate-cluster-agent stackstate/cluster-agent

Full details of the available values can be found in the Cluster Agent Helm Chart documentation (github.com).


To check the status of the Kubernetes integration, check that the StackState Cluster Agent (cluster-agent) pod and all of the StackState Agent (cluster-agent-agent) pods have status ready.

❯ kubectl get deployment,daemonset --namespace stackstate
deployment.apps/stackstate-cluster-agent 1/1 1 1 5h14m
daemonset.apps/stackstate-cluster-agent-agent 10 10 10 10 10 <none> 5h14m

Integration details

Data retrieved

The Kubernetes integration retrieves the following data:


The Kubernetes integration retrieves all events from the Kubernetes cluster. The table below shows which event category will be assigned to each event type in StackState:

StackState event category

Kubernetes events


BackOff ContainerGCFailed ExceededGracePeriod FileSystemResizeSuccessful ImageGCFailed Killing NodeAllocatableEnforced NodeNotReady NodeSchedulable Preempting Pulling Pulled Rebooted Scheduled Starting Started SuccessfulAttachVolume SuccessfulDetachVolume SuccessfulMountVolume SuccessfulUnMountVolume VolumeResizeSuccessful




Created (created container) NodeReady SandboxChanged SuccesfulCreate


All other events


The Kubernetes integration makes all metrics from the Kubernetes cluster available in StackState. Relevant metrics are automatically mapped to the associated components.

All retrieved metrics can be browsed or added to a component as a telemetry stream. Select the data source StackState Metrics and type kubernetes in the Select box to get a full list of all available metrics.

Add a Kubernetes metrics stream to a component


The Kubernetes integration retrieves components and relations for the Kubernetes cluster.


The following Kubernetes topology data is available in StackState as components:








Persistent Volume














The following relations between components are retrieved:

  • Container β†’ Volume

  • CronJob β†’ Job

  • DaemonSet β†’ Pod

  • Deployment β†’ ReplicaSet

  • Job β†’ Pod

  • Ingress β†’ Service

  • Namespace β†’ CronJob, DaemonSet, Deployment, Job, ReplicaSet, Service, StatefulSet

  • Node β†’ Cluster relation

  • Pod β†’ ConfigMap, Container, Deployment, Node, Secret, Volume

  • ReplicaSet β†’ Pod

  • Service β†’ ExternalService, Pod

  • StatefulSet β†’ Pod

  • Direct communication between processes

  • Process β†’ Process communication via Kubernetes service

  • Process β†’ Process communication via headless Kubernetes service


The Kubernetes integration does not retrieve any traces data.


All tags defined in Kubernetes will be retrieved and added to the associated components and relations in StackState.

REST API endpoints

The StackState Agent talks to the kubelet and kube-state-metrics API.

The StackState Agent and Cluster Agent connect to the Kubernetes API to retrieve cluster wide information and Kubernetes events. The following API endpoints used:

Resource type

REST API endpoint

Cluster > ComponentStatus

GET /api/v1/componentstatuses

Cluster > Event

GET /apis/events.k8s.io/v1/events

Cluster > Namespace

GET /api/v1/namespaces

Cluster > Node

GET /api/v1/nodes

Services > Endpoints

GET /api/v1/namespaces/{namespace}/endpoints

Services > Ingress

GET /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses

Services > Service

GET /api/v1/namespaces/{namespace}/services

Workloads > CronJob

GET /apis/batch/v1beta1/namespaces/{namespace}/cronjobs

Workloads > DaemonSet

GET /apis/apps/v1/namespaces/{namespace}/daemonsets

Workloads > Deployment

GET /apis/apps/v1/namespaces/{namespace}/deployments

Workloads > Job

GET /apis/batch/v1/namespaces/{namespace}/jobs

Workloads > Pod

GET /api/v1/namespaces/{namespace}/pods

Workloads > ReplicaSet

GET /apis/apps/v1/namespaces/{namespace}/replicasets

Workloads > StatefulSet

GET /apis/apps/v1/namespaces/{namespace}/statefulsets

Config and Storage > ConfigMap

GET /api/v1/namespaces/{namespace}/configmaps

Config and Storage > Secret

GET /api/v1/secrets

Config and Storage > PersistentVolume

GET /api/v1/persistentvolumes

Config and Storage > PersistentVolumeClaimSpec

GET /api/v1/namespaces/{namespace}/persistentvolumeclaims

Config and Storage > VolumeAttachment

GET /apis/storage.k8s.io/v1/volumeattachments





For further details, refer to the Kubernetes API documentation (kubernetes.io).

Component actions

A number of actions are added to StackState when the Kubernetes StackPack is installed. They are available from the Actions section on the right of the screen when a Kubernetes component is selected or from the component context menu, displayed when you hover over a Kubernetes component in the Topology Perspective


Available for component types


Show configuration and storage

pods containers

Display the selected pod or container with its configmaps, secrets and volumes

Show dependencies (deep)

deployment replicaset replicationcontroller statefulset daemonset job cronjob pod

Displays all dependencies (up to 6 levels deep) of the selected pod or workload.

Show pods

deployment replicaset replicationcontroller statefulset daemonset job cronjob

Displays the pods for the selected workload.

Show pods & services


Opens a view for the pods/services in the selected namespace

Show services


Open a view for the service and ingress components in the selected namespace

Show workloads


Show workloads in the selected namespace

Details of installed actions can be found in the StackState UI Settings > Actions > Component Actions screen.

Kubernetes views in StackState

When the Kubernetes integration is enabled, the following Kubernetes views are available in StackState for each cluster:

  • Kubernetes - Applications -

  • Kubernetes - Infrastructure -

  • Kubernetes - Namespaces -

  • Kubernetes - Workload Controllers -

Open source

The code for the StackState Agent Kubernetes check is open source and available on GitHub at:


Troubleshooting steps for any known issues can be found in the StackState support Knowledge base.


To uninstall the Kubernetes StackPack, go to the StackState UI StackPacks > Integrations > Kubernetes screen and click UNINSTALL. All Kubernetes StackPack specific configuration will be removed from StackState.

To uninstall the StackState Cluster Agent and the StackState Agent from your Kubernetes cluster, run a Helm uninstall:

helm uninstall <release_name> --namespace <namespace>
# If you used the standard install command provided when you installed the StackPack
helm uninstall stackstate-cluster-agent --namespace stackstate

Release notes

Kubernetes StackPack v3.9.1 (2021-04-02)

  • Improvement: Enable auto grouping on generated views.

  • Improvement: Update documentation.

  • Improvement: Common bumped from 2.4.1 to 2.5.0

  • Improvement: StackState min version bumped to 4.3.0

Kubernetes StackPack v3.8.0 (2021-03-08)

  • Feature: Namespaces are now a component in StackState with a namespaces view for each cluster

  • Feature: New component actions for quick navigation on workloads, pods and namespaces

  • Feature: Added a "Pod Scheduled" metric stream to pods

  • Feature: Secrets are now a component in StackState

  • Improvement: The "Desired vs Ready" checks on workloads now use the "Ready replicas" stream instead of the replicas stream.

  • Improvement: Use standard (blue) Kubernetes icons

  • Bug fix: Fixed Kubernetes synchronization when a component had no labels but only tags

Kubernetes StackPack v3.7.2 (2020-08-18)

  • Feature: Introduced the Release notes pop up for customer

Kubernetes StackPack v3.7.1 (2020-08-10)

  • Feature: Introduced Kubernetes specific component identifiers

Kubernetes StackPack v3.7.0 (2020-08-04)

  • Improvement: Deprecated stackpack specific layers and introduced a new common layer structure.

Kubernetes StackPack v3.6.0 (2020-06-19)

  • Improvement: Set the stream priorities on all streams.

See also