Comment on page
Agent V2 on Kubernetes
StackState SaaS
StackState Agent V2
To retrieve topology, events and metrics data from a Kubernetes or OpenShift cluster, you will need to have the following installed in the 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
To integrate with other services, a separate instance of StackState Agent V2 should be deployed on a standalone VM.
The Kubernetes and OpenShift integrations collect topology data from Kubernetes and OpenShift clusters respectively, as well as metrics and events. To achieve this, different types of StackState Agent are used:
Component | Pod name |
---|---|
stackstate-agent-node-agent | |
stackstate-agent-checks-agent | |
stackstate-agent-cluster-agent |
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 a Kubernetes or OpenShift cluster with checks that integrate with other services.
StackState Agents on Kubernetes
StackState Agent V2 is deployed as a DaemonSet with one instance on each node in the cluster:
- Host information is retrieved from the Kubernetes or OpenShift 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.
The StackState Checks Agent is an additional StackState Agent V2 pod that will run the cluster checks that are configured on the StackState Cluster Agent.
The following checks can be configured to run as a cluster check:
- The
kubernetes_state
check - this check gathers metrics from kube-state-metrics and sends them to StackState. - The Checks Agent is also useful to run checks that do not need to run on a specific node and monitor non-containerized workloads such as:
- Out-of-cluster datastores and endpoints (for example, RDS or CloudSQL).
- Load-balanced cluster services (for example, Kubernetes services).
StackState Cluster Agent is deployed as a Deployment. There is one instance for the entire 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 or OpenShift API
StackState Agent v2.18.x is supported to monitor the following versions of Kubernetes or OpenShift:
- Kubernetes:
- Kubernetes 1.16 - 1.21
- EKS (with Kubernetes 1.16 - 1.21)
- OpenShift:
- OpenShift 4.3 - 4.8
- Default networking
- Container runtime:
- Docker
- containerd
- CRI-O
The StackState Agent, Cluster Agent, Checks Agent and kube-state-metrics can be installed together using the StackState Agent Helm Chart:
- Online install - charts are retrieved from the default StackState chart repository (https://helm.stackstate.io), images are retrieved from the default StackState image registry (quay.io).
The StackState Agent, Cluster Agent, Checks Agent and kube-state-metrics can be installed together using the StackState 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.iohelm repo update
- 2.Deploy the StackState Agent, Cluster Agent, Checks Agent and kube-state-metrics to namespace
stackstate
using the helm command below.<STACKSTATE_RECEIVER_API_KEY>
is set during StackState installation.<STACKSTATE_RECEIVER_API_ADDRESS>
is specific to your installation of StackState.
Kubernetes
OpenShift
helm upgrade --install \
--namespace stackstate \
--create-namespace \
--set-string 'stackstate.apiKey'='<STACKSTATE_RECEIVER_API_KEY>' \
--set-string 'stackstate.cluster.name'='<KUBERNETES_CLUSTER_NAME>' \
--set-string 'stackstate.url'='<STACKSTATE_RECEIVER_API_ADDRESS>' \
stackstate-agent stackstate/stackstate-agent
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.url'='<STACKSTATE_RECEIVER_API_ADDRESS>' \
--set 'agent.scc.enabled'=true \
--set 'kube-state-metrics.securityContext.enabled'=false \
stackstate-agent stackstate/stackstate-agent
If StackState Agent will run in an environment that does not have a direct connection to the Internet, the images required to install the StackState Agent, Cluster Agent, Checks Agent and kube-state-metrics can be downloaded and stored in a local system or image registry.
- 1.Internet connection required:
- 1.Download or clone the StackState Helm charts repo from GitHub: https://github.com/StackVista/helm-charts
- 2.In the Helm charts repo, go to the directory
stable/stackstate-agent/installation
and use the scriptbackup.sh
to back up the required images from StackState. The script will pull all images required for thestackstate-agent
Helm chart to run, back them up to individual tar archives and add all tars to a singletar.gz
archive. The images will be in atar.gz
archive in the same folder as the working directory from where the script was executed. It is advised to run the script from thestable/stackstate-agent/installation
directory as this will simplify the process of importing images on the destination system.- By default, the backup script will retrieve charts from the StackState chart repository (https://helm.stackstate.io), images are retrieved from the default StackState image registry (quay.io). The script can be executed from the
installation
directory as simply./backup.sh
.Back up helm chart images to a tar.gz archive for easy transport via an external storage device.Arguments:-c : Helm chart (default: stackstate/stackstate-agent)-h : Show this help text-r : Helm repository (default: https://helm.stackstate.io)-t : Dry-run - Add the
-t
(dry-run) parameter to the script to give a predictive output of what work will be performed, for example:./backup.sh -tBacking up quay.io/stackstate/stackstate-agent-2:2.18.0 to stackstate/stackstate-agent-2__2.18.0.tar (dry-run)Backing up quay.io/stackstate/stackstate-process-agent:4.0.7 to stackstate/stackstate-process-agent__4.0.7.tar (dry-run)Backing up quay.io/stackstate/kube-state-metrics:2.3.0-focal-20220316-r61.20220418.2032 to stackstate/kube-state-metrics__2.3.0-focal-20220316-r61.20220418.2032.tar (dry-run)Backing up quay.io/stackstate/stackstate-agent-cluster-agent:2.18.0 to stackstate/stackstate-agent-cluster-agent__2.18.0.tar (dry-run)Backing up quay.io/stackstate/stackstate-agent-2:2.18.0 to stackstate/stackstate-agent-2__2.18.0.tar (dry-run)Images have been backed up to stackstate.tar.gz
- 2.No internet connection required:
- 1.Transport images to the destination system.
- Copy the StackState Helm charts repo, including the
tar.gz
generated by the backup script, to a storage device for transportation. If the backup script was run from thestable/stackstate-agent/installation
directory as advised, thetar.gz
will be located atstable/stackstate-agent/installation/stackstate.tar.gz
. - Copy the Helm charts repo and
tar.gz
from the storage device to a working folder of choice on the destination system.
- 2.Import images to the system, and optionally push to a registry.
- On the destination system, go to the directory in the StackState Helm charts repo that contains both the scripts and the generated
tar.gz
archive. By default, this will bestable/stackstate-agent/installation
. - Execute the
import.sh
script. Note that the import script must be located in the same directory as thetar.gz
archive to be imported, the following must be specified:-b
- path to thetar.gz
to be imported-d
- the destination Docker image registry
- Additional options when running the script:
-p
- push images to the destination registry. When not specified, images will be imported and tagged, but remain on the local machine.-t
- Dry-run. Use to show the work that will be performed without any action being taken.
Example script usage
In the example below, the StackState Agent images will be extracted from the archive
stackstate.tar.gz
, imported by Docker, and re-tagged to the registry given by the -d
flag, in this example, localhost
. The -t
argument (dry-run) is provided to show the work that will be performed:./import.sh -b stackstate.tar.gz -d localhost -t