kube-state-metrics (KSM) is a simple service that listens to the Kubernetes API server and generates metrics about the state of Kubernetes objects. It provides valuable insights into cluster health by exposing metrics for deployments, nodes, pods, and other Kubernetes resources without modifying the objects themselves.
This kube-state-metrics distribution is provided by the Sourcemation packaging team, built on a secure Debian 13 Slim base image with kube-state-metrics.
kube-state-metrics is designed to be deployed within a Kubernetes cluster. Below are common deployment patterns.
This example deploys kube-state-metrics as a single-replica Deployment. This is suitable for most small to medium-sized clusters.
apiVersion: v1
kind: ServiceAccount
metadata:
name: kube-state-metrics
namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: kube-state-metrics
rules:
- apiGroups: [""]
resources:
- configmaps
- secrets
- nodes
- pods
- services
- resourcequotas
- replicationcontrollers
- limitranges
- persistentvolumeclaims
- persistentvolumes
- namespaces
- endpoints
verbs: ["list", "watch"]
- apiGroups: ["apps"]
resources:
- statefulsets
- daemonsets
- deployments
- replicasets
verbs: ["list", "watch"]
- apiGroups: ["batch"]
resources:
- cronjobs
- jobs
verbs: ["list", "watch"]
- apiGroups: ["autoscaling"]
resources:
- horizontalpodautoscalers
verbs: ["list", "watch"]
- apiGroups: ["policy"]
resources:
- poddisruptionbudgets
verbs: ["list", "watch"]
- apiGroups: ["certificates.k8s.io"]
resources:
- certificatesigningrequests
verbs: ["list", "watch"]
- apiGroups: ["storage.k8s.io"]
resources:
- storageclasses
- volumeattachments
verbs: ["list", "watch"]
- apiGroups: ["admissionregistration.k8s.io"]
resources:
- mutatingwebhookconfigurations
- validatingwebhookconfigurations
verbs: ["list", "watch"]
- apiGroups: ["networking.k8s.io"]
resources:
- networkpolicies
- ingresses
verbs: ["list", "watch"]
- apiGroups: ["coordination.k8s.io"]
resources:
- leases
verbs: ["list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: kube-state-metrics
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: kube-state-metrics
subjects:
- kind: ServiceAccount
name: kube-state-metrics
namespace: kube-system
---
apiVersion: v1
kind: Service
metadata:
name: kube-state-metrics
namespace: kube-system
labels:
app.kubernetes.io/name: kube-state-metrics
app.kubernetes.io/version: v2.17.0
spec:
clusterIP: None
ports:
- name: http-metrics
port: 8080
targetPort: http-metrics
protocol: TCP
- name: telemetry
port: 8081
targetPort: telemetry
protocol: TCP
selector:
app.kubernetes.io/name: kube-state-metrics
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: kube-state-metrics
namespace: kube-system
labels:
app.kubernetes.io/name: kube-state-metrics
app.kubernetes.io/version: v2.17.0
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: kube-state-metrics
template:
metadata:
labels:
app.kubernetes.io/name: kube-state-metrics
app.kubernetes.io/version: v2.17.0
spec:
serviceAccountName: kube-state-metrics
containers:
- name: kube-state-metrics
image: sourcemation/kube-state-metrics:latest
ports:
- name: http-metrics
containerPort: 8080
- name: telemetry
containerPort: 8081
livenessProbe:
httpGet:
path: /livez
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 5
readinessProbe:
httpGet:
path: /readyz
port: 8081
initialDelaySeconds: 5
timeoutSeconds: 5
resources:
requests:
cpu: 100m
memory: 250Mi
limits:
cpu: 200m
memory: 500Mi
For large clusters, you can deploy kube-state-metrics with automatic sharding using a StatefulSet to horizontally scale and distribute the load.
apiVersion: v1
kind: Service
metadata:
name: kube-state-metrics
namespace: kube-system
labels:
app.kubernetes.io/name: kube-state-metrics
spec:
clusterIP: None
ports:
- name: http-metrics
port: 8080
targetPort: http-metrics
- name: telemetry
port: 8081
targetPort: telemetry
selector:
app.kubernetes.io/name: kube-state-metrics
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: kube-state-metrics
namespace: kube-system
spec:
serviceName: "kube-state-metrics"
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: kube-state-metrics
template:
metadata:
labels:
app.kubernetes.io/name: kube-state-metrics
spec:
serviceAccountName: kube-state-metrics
containers:
- name: kube-state-metrics
image: sourcemation/kube-state-metrics:latest
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
args:
- --pod=$(POD_NAME)
- --pod-namespace=$(POD_NAMESPACE)
ports:
- name: http-metrics
containerPort: 8080
- name: telemetry
containerPort: 8081
resources:
requests:
cpu: 100m
memory: 150Mi
limits:
cpu: 200m
memory: 300Mi
Deploy as a DaemonSet to collect node-specific pod metrics. This pattern is useful for getting detailed metrics on a per-node basis.
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: kube-state-metrics
namespace: kube-system
labels:
app.kubernetes.io/name: kube-state-metrics
spec:
selector:
matchLabels:
app.kubernetes.io/name: kube-state-metrics
template:
metadata:
labels:
app.kubernetes.io/name: kube-state-metrics
spec:
serviceAccountName: kube-state-metrics
containers:
- name: kube-state-metrics
image: sourcemation/kube-state-metrics:latest
env:
- name: NODE_NAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
args:
- --resource=pods
- --node=$(NODE_NAME)
ports:
- name: http-metrics
containerPort: 8080
- name: telemetry
containerPort: 8081
resources:
requests:
cpu: 50m
memory: 100Mi
limits:
cpu: 100m
memory: 200Mi
---
# Deployment for unscheduled pods
apiVersion: apps/v1
kind: Deployment
metadata:
name: kube-state-metrics-unscheduled
namespace: kube-system
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: kube-state-metrics-unscheduled
template:
metadata:
labels:
app.kubernetes.io/name: kube-state-metrics-unscheduled
spec:
serviceAccountName: kube-state-metrics
containers:
- name: kube-state-metrics
image: sourcemation/kube-state-metrics:latest
args:
- --resources=pods
- --track-unscheduled-pods
ports:
- name: http-metrics
containerPort: 8080
- name: telemetry
containerPort: 8081
This image uses the following environment variables:
This image exposes the following ports:
/metrics)The kube-state-metrics server supports various command-line arguments for configuration, which can be passed via the args field in your Kubernetes manifests. Here are the most commonly used ones:
--resources - Comma-separated list of resources to be enabled (default: all resources)
--resources=pods,deployments,nodes--namespaces - Comma-separated list of namespaces to monitor (default: all namespaces)--namespace - Single namespace to monitor (alternative to --namespaces)--metric-allowlist - Comma-separated list of metrics to expose (default: all metrics)--metric-denylist - Comma-separated list of metrics to exclude--metric-labels-allowlist - Comma-separated list of additional Kubernetes label keys to expose as labels
resource=[label1,label2],resource2=[*]--shard - Shard ordinal (zero-indexed) for horizontal sharding--total-shards - Total number of shards for horizontal sharding--pod - Pod name for automatic shard discovery in StatefulSet--pod-namespace - Pod namespace for automatic shard discovery--node - Node name for filtering pod metrics (used in DaemonSet deployments)--track-unscheduled-pods - Track pods that are not scheduled to any node--host - Host to expose metrics on (default: ::)--port - Port to expose metrics on (default: 8080)--telemetry-host - Host to expose telemetry on (default: ::)--telemetry-port - Port to expose telemetry on (default: 8081)--kubeconfig - Path to kubeconfig file for Kubernetes API access--apiserver - Override the API server address in kubeconfig--use-apiserver-cache - Use API server cache to reduce latency and etcd load--log - Log level (debug, info, warn, error, fatal, panic) (default: info)--enable-gzip-encoding - Enable gzip encoding for /metrics endpoint--custom-resource-state-config - Inline custom resource state configuration--custom-resource-state-config-file - Path to custom resource state configuration file--custom-resource-state-only - Only expose custom resource state metricsMonitor specific resources only:
kube-state-metrics --resources=deployments,pods,statefulsets
Monitor specific namespaces:
kube-state-metrics --namespaces=production,staging
Enable sharding (instance 0 of 3):
kube-state-metrics --shard=0 --total-shards=3
Expose only specific metrics:
kube-state-metrics --metric-allowlist=kube_pod_info,kube_deployment_status_replicas
kube-state-metrics provides built-in health check endpoints:
/healthz - Returns 200 if the application is running (startup probe)/livez - Returns 200 if the application is not affected by a Kubernetes API outage (liveness probe)/readyz - Returns 200 if the application is ready to serve metrics (readiness probe)Example health check configuration:
livenessProbe:
httpGet:
path: /livez
port: 8080
initialDelaySeconds: 5
periodSeconds: 10
readinessProbe:
httpGet:
path: /readyz
port: 8081
initialDelaySeconds: 5
periodSeconds: 10
All metrics are exposed at the /metrics endpoint on port 8080. The metrics are available in Prometheus text format and can be scraped by Prometheus or any compatible monitoring system.
Example metrics:
kube_pod_info{namespace="default",pod="example-pod",host_ip="10.0.0.1"} 1
kube_pod_status_phase{namespace="default",pod="example-pod",phase="Running"} 1
kube_deployment_status_replicas{namespace="default",deployment="example"} 3
kube_node_status_condition{node="node-1",condition="Ready",status="true"} 1
Configure Prometheus to scrape kube-state-metrics:
scrape_configs:
- job_name: 'kube-state-metrics'
static_configs:
- targets: ['kube-state-metrics.kube-system.svc.cluster.local:8080']
metric_relabel_configs:
- action: labeldrop
regex: (uid|pod_ip)
For Kubernetes service discovery:
scrape_configs:
- job_name: 'kube-state-metrics'
kubernetes_sd_configs:
- role: service
relabel_configs:
- source_labels: [__meta_kubernetes_service_label_app_kubernetes_io_name]
action: keep
regex: kube-state-metrics
- source_labels: [__meta_kubernetes_service_port_name]
action: keep
regex: http-metrics
This image runs as the nobody user (non-root) for enhanced security. The container follows security best practices and is built on a minimal Debian 13 Slim base image.
Based on cluster size, recommended resource allocations are:
Small clusters (< 100 nodes):
Medium clusters (100-500 nodes):
Large clusters (> 500 nodes):
Note: If you experience high memory usage or CPU throttling, consider implementing horizontal sharding.
For large clusters, kube-state-metrics can be horizontally scaled using sharding. Sharding distributes the workload across multiple instances by using an md5 hash of each object's UID.
Benefits:
Considerations:
For optimal performance:
--use-apiserver-cache to reduce latency and etcd load--metric-allowlist to reduce cardinalityWe'd love for you to contribute! You can request new features, report bugs, or submit a pull request with your contribution to this image on the Sourcemation GitHub repository.
Disclaimer: The sourcemation/kube-state-metrics image is not affiliated with the Kubernetes project. The respective companies and organisations own the trademarks mentioned in the offering. The sourcemation/kube-state-metrics image is a separate project and is maintained by Sourcemation.
A detailed risk analysis report of the image and its components can be found on the Sourcemation platform.
For more information, check out the kube-state-metrics documentation.
The base license for the solution (kube-state-metrics) is the Apache License 2.0. The licenses for each component shipped as part of this image can be found on the image's appropriate Sourcemation entry.
Content type
Image
Digest
sha256:da2a30bf6…
Size
52.4 MB
Last updated
15 days ago
docker pull sourcemation/kube-state-metrics