146 lines
6.6 KiB
Markdown
146 lines
6.6 KiB
Markdown
# Documentation
|
||
|
||
This documentation is intended to be a complete reflection of the current state of the exposed metrics of kube-state-metrics.
|
||
|
||
Any contribution to improving this documentation or adding sample usages will be appreciated.
|
||
|
||
## Table of Contents
|
||
|
||
* [Metrics Stages](#metrics-stages)
|
||
* [Exposed Metrics](#exposed-metrics)
|
||
* [Join Metrics](#join-metrics)
|
||
* [CLI arguments](#cli-arguments)
|
||
|
||
## Metrics Stages
|
||
|
||
Stages about metrics are grouped into three categories：
|
||
|
||
| Stage | Description |
|
||
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
||
| EXPERIMENTAL | Metrics which normally correspond to the Kubernetes API object alpha status or spec fields and can be changed at any time. |
|
||
| STABLE | Metrics which should have very few backwards-incompatible changes outside of major version updates. |
|
||
| DEPRECATED | Metrics which will be removed once the deprecation timeline is met. |
|
||
|
||
## Opt-in Metrics
|
||
|
||
As of v2.3.0, kube-state-metrics supports additional opt-in metrics via the CLI flag `--metric-opt-in-list`. See the metric documentation to identify which metrics need to be specified.
|
||
|
||
## Exposed Metrics
|
||
|
||
Per group of metrics there is one file for each metrics.
|
||
See each file for specific documentation about the exposed metrics:
|
||
|
||
### Default Resources
|
||
|
||
* [CertificateSigningRequest Metrics](metrics/auth/certificatesigningrequest-metrics.md)
|
||
* [ConfigMap Metrics](metrics/storage/configmap-metrics.md)
|
||
* [CronJob Metrics](metrics/workload/cronjob-metrics.md)
|
||
* [DaemonSet Metrics](metrics/workload/daemonset-metrics.md)
|
||
* [Deployment Metrics](metrics/workload/deployment-metrics.md)
|
||
* [Endpoint Metrics](metrics/service/endpoint-metrics.md)
|
||
* [Horizontal Pod Autoscaler Metrics](metrics/workload/horizontalpodautoscaler-metrics.md)
|
||
* [Ingress Metrics](metrics/service/ingress-metrics.md)
|
||
* [Job Metrics](metrics/workload/job-metrics.md)
|
||
* [Lease Metrics](metrics/cluster/lease-metrics.md)
|
||
* [LimitRange Metrics](metrics/policy/limitrange-metrics.md)
|
||
* [MutatingWebhookConfiguration Metrics](metrics/extend/mutatingwebhookconfiguration-metrics.md)
|
||
* [Namespace Metrics](metrics/cluster/namespace-metrics.md)
|
||
* [NetworkPolicy Metrics](metrics/policy/networkpolicy-metrics.md)
|
||
* [Node Metrics](metrics/cluster/node-metrics.md)
|
||
* [PersistentVolume Metrics](metrics/storage/persistentvolume-metrics.md)
|
||
* [PersistentVolumeClaim Metrics](metrics/storage/persistentvolumeclaim-metrics.md)
|
||
* [Pod Disruption Budget Metrics](metrics/policy/poddisruptionbudget-metrics.md)
|
||
* [Pod Metrics](metrics/workload/pod-metrics.md)
|
||
* [ReplicaSet Metrics](metrics/workload/replicaset-metrics.md)
|
||
* [ReplicationController Metrics](metrics/workload/replicationcontroller-metrics.md)
|
||
* [ResourceQuota Metrics](metrics/policy/resourcequota-metrics.md)
|
||
* [Secret Metrics](metrics/storage/secret-metrics.md)
|
||
* [Service Metrics](metrics/service/service-metrics.md)
|
||
* [StatefulSet Metrics](metrics/workload/statefulset-metrics.md)
|
||
* [StorageClass Metrics](metrics/storage/storageclass-metrics.md)
|
||
* [ValidatingWebhookConfiguration Metrics](metrics/extend/validatingwebhookconfiguration-metrics.md)
|
||
* [VolumeAttachment Metrics](metrics/storage/volumeattachment-metrics.md)
|
||
|
||
### Optional Resources
|
||
|
||
* [ClusterRole Metrics](metrics/cluster/clusterrole-metrics.md)
|
||
* [ClusterRoleBinding Metrics](metrics/cluster/clusterrolebinding-metrics.md)
|
||
* [EndpointSlice Metrics](metrics/service/endpointslice-metrics.md)
|
||
* [IngressClass Metrics](metrics/service/ingressclass-metrics.md)
|
||
* [Role Metrics](metrics/auth/role-metrics.md)
|
||
* [RoleBinding Metrics](metrics/auth/rolebinding-metrics.md)
|
||
* [ServiceAccount Metrics](metrics/auth/serviceaccount-metrics.md)
|
||
|
||
## Join Metrics
|
||
|
||
When an additional, not provided by default label is needed, a [Prometheus matching operator](https://prometheus.io/docs/prometheus/latest/querying/operators/#vector-matching)
|
||
can be used to extend single metrics output.
|
||
|
||
This example adds `label_release` to the set of default labels of the `kube_pod_status_ready` metric
|
||
and allows you select or group the metrics by Helm release label:
|
||
|
||
```promql
|
||
kube_pod_status_ready * on (namespace, pod) group_left(label_release) kube_pod_labels
|
||
```
|
||
|
||
Another useful example would be to query the memory usage of pods by its `phase`, such as `Running`:
|
||
|
||
```promql
|
||
sum(kube_pod_container_resource_requests{resource="memory"}) by (namespace, pod, node)
|
||
* on (namespace, pod) group_left() (sum(kube_pod_status_phase{phase="Running"}) by (pod, namespace) == 1)
|
||
```
|
||
|
||
## Metrics from Custom Resources
|
||
|
||
See [Custom Resource State Metrics](metrics/extend/customresourcestate-metrics.md) for experimental support for custom resources.
|
||
|
||
## CLI Arguments
|
||
|
||
Additionally, options for `kube-state-metrics` can be passed when executing as a CLI, or in a kubernetes / openshift environment. More information can be found here: [CLI Arguments](developer/cli-arguments.md)
|
||
|
||
## Protecting /metrics endpoints
|
||
|
||
Kube-State-Metrics' metrics can contain sensitive information about the state of the cluster, which you as an operator might want to additionally protect from unauthorized access.
|
||
In order to achieve this, you need to enable the `--auth-filter` flag on kube-state-metrics.
|
||
With this, kube-state-metrics will only accept authenticated and authorized requests to the /metrics endpoints.
|
||
Kube-state-metrics uses Kubernetes' RBAC mechanisms for this, so this means that every scrape will trigger a request against the API Server for TokenReview and SubjectAccessReview.
|
||
The clients scraping the endpoint, need to use a token which can be provided by a ServiceAccount that can be set up the following way:
|
||
|
||
A ClusterRole providing access like this:
|
||
|
||
```yaml
|
||
apiVersion: rbac.authorization.k8s.io/v1
|
||
kind: ClusterRole
|
||
metadata:
|
||
name: metrics-reader
|
||
rules:
|
||
- nonResourceURLs:
|
||
- "/metrics"
|
||
verbs:
|
||
- get
|
||
```
|
||
|
||
and a matching ClusterRoleBinding
|
||
|
||
```yaml
|
||
apiVersion: rbac.authorization.k8s.io/v1
|
||
kind: ClusterRoleBinding
|
||
metadata:
|
||
name: metrics-reader-rolebinding
|
||
roleRef:
|
||
apiGroup: rbac.authorization.k8s.io
|
||
kind: ClusterRole
|
||
name: metrics-reader
|
||
subjects:
|
||
- kind: ServiceAccount
|
||
name: YOUR_SERVICE_ACCOUNT
|
||
namespace: NAMESPACE_OF_THE_SERVICE_ACCOUNT
|
||
```
|
||
|
||
Your client can then use either this ServiceAccount to gather metrics or you can create a token, that can be used to fetch data like this:
|
||
|
||
```bash
|
||
TOKEN=$(kubectl create token YOUR_SERVICE_ACCOUNT -n NAMESPACE_OF_THE_SERVICE_ACCOUNT)
|
||
curl -H "Authorization: Bearer $TOKEN" KUBE_STATE_METRICS_URL:8080/metrics
|
||
```
|