OpenShift
StackState SaaS
Last updated
StackState SaaS
Last updated
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:
Workloads
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.
Data is retrieved by the deployed StackState Agents and then pushed to StackState via the Agent StackPack and the OpenShift StackPack.
In StackState:
Topology data is translated into components and relations.
Tags defined in OpenShift 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.
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.
Object change events are created for every detected change to spec
or metadata
in OpenShift objects
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:
containerd
CRI-O
Docker
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
kube-state-metrics
➡️ Deploy StackState Agents and kube-state-metrics.
To integrate with other services, a separate instance of the StackState Agent should be deployed on a standalone VM. It is not currently possible to configure a StackState Agent deployed on an OpenShift cluster with checks that integrate with other services.
The kubernetes_state check is responsible for gathering metrics from kube-state-metrics and sending them to StackState. The kubernetes_state check runs in the StackState Checks Agent by default and is configured in the StackState Cluster Agent.
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:
Update the values.yaml
file used to deploy the checks-agent
, for example:
Deploy the checks_agent
using the updated values.yaml
:
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.
The OpenShift integration retrieves the following data:
The OpenShift integration retrieves all OpenShift events from the OpenShift cluster. In addition to this, Element Properties Change
events will be generated in StackState for changes in Kubernetes objects.
All OpenShift events are retrieved from the Kubernetes cluster.
StackState Element Properties Change
events will be generated for changes detected in an OpenShift object.
OpenShift events
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:
Activities
BackOff
ContainerGCFailed
ExceededGracePeriod
FileSystemResizeSuccessful
ImageGCFailed
Killing
NodeAllocatableEnforced
NodeNotReady
NodeSchedulable
Preempting
Pulling
Pulled
Rebooted
Scheduled
Starting
Started
SuccessfulAttachVolume
SuccessfulDetachVolume
SuccessfulMountVolume
SuccessfulUnMountVolume
VolumeResizeSuccessful
Alerts
NotTriggerScaleUp
Changes
Created
(created container) NodeReady
SandboxChanged
SuccesfulCreate
Others
All other events
Object change events
The OpenShift integration will detect changes in OpenShift objects and will create an event of type Element Properties Change
with a diff with a YAML representation of the changed object.
Changes will be detected in the following object types:
ConfigMap
CronJob
DaemonSet
Deployment
Ingress
Job
Namespace
Node
PersistentVolume
Pod
ReplicaSet
Secret
(a hash of the content will be compared)
Service
StatefulSet
Note that, in order to reduce noise of changes, the following object properties will not be compared:
metadata
managedFields
resourceVersion
annotations
kubectl.kubernetes.io/last-applied-configuration
status
(except for Node
, Pod
and PersistentVolume
objects)
You can also see current (or past) YAML definition of the object in the "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 kubernetes
in the Select box to get a full list of all available metrics.
The OpenShift integration retrieves components and relations for the OpenShift cluster.
StackState Agent versions prior to 2.16: Topology information is only gathered from OpenShift clusters that use the Docker container runtime.
Components
The following OpenShift topology data is available in StackState as components:
Cluster
Ingress
Namespace
Job
Node
Persistent Volume
Pod
ReplicaSet
Container
Secret
ConfigMap
Service
CronJob
StatefulSet
DaemonSet
Volume
Deployment
Relations
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:
image_name
kube_cluster_name
kube_container_name
kube_cronjob
kube_daemon_set
kube_deployment
kube_job
kube_namespace
kube_replica_set
kube_replication_controller
kube_stateful_set
pod_name
pod_phase
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:
Metadata > ComponentStatus
GET /api/v1/componentstatuses
Metadata > ConfigMap
GET /api/v1/namespaces/{namespace}/configmaps
Metadata > Event
GET /apis/events.k8s.io/v1/events
Metadata > Namespace
GET /api/v1/namespaces
Network > Endpoints
GET /api/v1/namespaces/{namespace}/endpoints
Network > Ingress
GET /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses
Network > Service
GET /api/v1/namespaces/{namespace}/services
Node > Node
GET /api/v1/nodes
Security > Secret
GET /api/v1/secrets
Storage > PersistentVolumeClaimSpec
GET /api/v1/namespaces/{namespace}/persistentvolumeclaims
Storage > VolumeAttachment
GET /apis/storage.k8s.io/v1/volumeattachments
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 > PersistentVolume
GET /api/v1/persistentvolumes
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
/version
/healthz
For further details, refer to the OpenShift API documentation (openshift.com).
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
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 and services
namespace
Opens a view for the pods/services in the selected namespace
Show services
namespace
Open a view for the service and ingress components in the selected namespace
Show workloads
namespace
Show workloads in the selected namespace
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:
Troubleshooting steps for any known issues can be found in the StackState support Knowledge base.
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.
See the Kubernetes Agent documentation for instructions on how to uninstall the StackState Cluster Agent and the StackState Agent from your Openshift cluster.
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 agent.containerRuntime.customSocketPath
option.
OpenShift StackPack v3.7.9 (2021-11-30)
Bug Fix: Support nodes without instanceId