StackState Self-hosted v5.1.x
The OpenShift integration is used to create a near real-time synchronization of topology and associated internal services from an OpenShift cluster to StackState. This StackPack allows monitoring of the following:
- Nodes, pods, containers and services
- Configmaps, secrets and volumes
The OpenShift integration collects topology data in an OpenShift cluster as well as metrics and events.
- In StackState:
- OpenShift events are available in the StackState UI Events Perspective. They are also included the Event list in the right panel View summary tab and the details tabs - Component details and Direct relation details.
The following prerequisites are required to install the OpenShift StackPack and deploy the StackState Agent and Cluster Agent:
- An OpenShift Cluster must be up and running.
- A recent version of Helm 3.
- A user with permissions to create privileged pods, ClusterRoles, ClusterRoleBindings and SCCs:
- ClusterRole and ClusterRoleBinding are needed to grant StackState Agents permissions to access the OpenShift API.
- StackState Agents need to run in a privileged pod to be able to gather information on network connections and host information.
From StackState Agent V2.16, the following container runtimes are supported:
Note that versions of StackState Agent prior to v2.16 support the Docker container runtime only.
Install the OpenShift StackPack from the StackState UI StackPacks > Integrations screen. You will need to provide the following parameters:
- OpenShift 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 OpenShift StackPack. This is required to work with the StackState Agent, which will need to be deployed on each node in the OpenShift cluster.
For the OpenShift integration to retrieve topology, events and metrics data, you will need to have the following installed on your OpenShift cluster:
- StackState Agent V2 on each node in the cluster
- StackState Cluster Agent on one node
- StackState Checks Agent on one node
The default URL that the kubernetes_state check uses is:
If an alternative kube-state-metrics pod (i.e. Prometheus) is installed, the default StackState kube-state-metrics pod can be disabled and the kubernetes_state check redirected to the alternative service:
- 1.Update the
values.yamlfile used to deploy the
checks-agent, for example:dependencies:kubeStateMetrics:enabled: falsechecksAgent:kubeStateMetrics:url: http://YOUR_KUBE_STATE_METRICS_SERVICE_NAME:8080/metrics
- 2.Deploy the
checks_agentusing the updated
values.yaml:helm upgrade --install \--namespace stackstate \--create-namespace \--set-string 'stackstate.apiKey'='<STACKSTATE_RECEIVER_API_KEY>' \--set-string 'stackstate.cluster.name'='<OPENSHIFT_CLUSTER_NAME>' \--set-string 'stackstate.cluster.authToken=<CLUSTER_AUTH_TOKEN>' \--set-string 'stackstate.url'='<STACKSTATE_RECEIVER_API_ADDRESS>' \--set 'agent.scc.enabled'=true \--set 'kube-state-metrics.securityContext.enabled'=false \--values values.yaml \stackstate-agent stackstate/stackstate-agent
To check the status of the OpenShift integration, check that the StackState Cluster Agent (
cluster-agent) pod, StackState Checks Agent pod (
checks-agent) and all of the StackState Agent (
node-agent) pods have status ready.
❯ kubectl get deployment,daemonset --namespace stackstate
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/stackstate-agent-cluster-agent 1/1 1 1 5h14m
deployment.apps/stackstate-agent-checks-agent 1/1 1 1 5h14m
NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE
daemonset.apps/stackstate-agent-node-agent 10 10 10 10 10 <none> 5h14m
The OpenShift integration retrieves the following data:
The OpenShift integration retrieves all OpenShift events from the OpenShift cluster. In addition to this,
Element Properties Changeevents will be generated in StackState for changes in Kubernetes objects.
The OpenShift integration retrieves all events from the OpenShift cluster. The table below shows which event category will be assigned to each event type in StackState:
Object change events
The OpenShift integration will detect changes in OpenShift objects and will create an event of type
Element Properties Changewith a diff with a YAML representation of the changed object.
Element Properties Change event
Changes will be detected in the following object types:
Secret(a hash of the content will be compared)
OpenShift Component properties
The OpenShift integration makes all metrics from the OpenShift 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
kubernetesin the Select box to get a full list of all available metrics.
Add an OpenShift metrics stream to a component
The OpenShift integration retrieves components and relations for the OpenShift cluster.
The following OpenShift topology data is available in StackState as components:
The following relations between components are retrieved:
- Container → PersistentVolume, 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, PersistentVolume, Secret, Volume
- ReplicaSet → Pod
- Service → ExternalService, Pod
- StatefulSet → Pod
- Direct communication between processes
- Process → Process communication via OpenShift service
- Process → Process communication via headless OpenShift service
The OpenShift integration does not retrieve any traces data.
All tags defined in OpenShift will be retrieved and added to the associated components and relations in StackState as labels.
The following labels will also be added to imported elements as relevant:
The StackState Agent talks to the kubelet and kube-state-metrics API.
The StackState Agent and Cluster Agent connect to the OpenShift API to retrieve cluster wide information and OpenShift events. The following API endpoints used:
A number of actions are added to StackState when the OpenShift StackPack is installed. They are available from the Actions section in the right panel details tab - Component details - when an OpenShift component is selected or from the component context menu, which is displayed when you hover the mouse pointer over an OpenShift component in the Topology Perspective
Details of installed actions can be found in the StackState UI Settings > Actions > Component Actions screen.
When the OpenShift integration is enabled, the following OpenShift views are available in StackState for each cluster:
- OpenShift - Applications -
- OpenShift - Infrastructure -
- OpenShift - Namespaces -
- OpenShift - Workload Controllers -
The code for the StackState Agent OpenShift check is open source and available on GitHub at:
To uninstall the OpenShift StackPack, go to the StackState UI StackPacks > Integrations > OpenShift screen and click UNINSTALL. All OpenShift StackPack specific configuration will be removed from StackState.
OpenShift StackPack v3.8.2 (2022-09-28)
- Improvement: Updated documentation.
OpenShift StackPack v3.8.1 (2022-09-15)
- Improvement: Added validation for cluster name
OpenShift StackPack v3.7.13 (2022-06-21)
- Bug Fix: Fixed description for services/ingresses view.
OpenShift StackPack v3.7.12 (2022-06-03)
- Improvement: Updated documentation.
OpenShift StackPack v3.7.11 (2022-05-23)
- Bug Fix: Fixed broken link in integration StackState Agent V2 integration documentation.
OpenShift StackPack v3.7.10 (2022-03-02)
- Improvement: Documentation for
OpenShift StackPack v3.7.9 (2021-11-30)
- Bug Fix: Support nodes without instanceId