[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-9948":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":23,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":35,"discoverSource":36},9948,"kube-state-metrics","kubernetes\u002Fkube-state-metrics","kubernetes","Add-on agent to generate and expose cluster-level metrics.","https:\u002F\u002Fkubernetes.io\u002Fdocs\u002Fconcepts\u002Fcluster-administration\u002Fkube-state-metrics\u002F",null,"Go",6138,2187,76,70,0,2,16,68.6,"Apache License 2.0",false,"main",true,[7,25,26,27,28,29,30,31],"kubernetes-exporter","kubernetes-monitoring","metrics","monitoring","observability","prometheus","prometheus-exporter","2026-06-12 04:00:47","# Overview\n\n[![Build Status](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics\u002Fworkflows\u002Fcontinuous-integration\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics\u002Factions)\n[![Go Report Card](https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics)\n[![Go Reference](https:\u002F\u002Fpkg.go.dev\u002Fbadge\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics.svg)](https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics)\n[![govulncheck](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics\u002Factions\u002Fworkflows\u002Fgovulncheck.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics\u002Factions\u002Fworkflows\u002Fgovulncheck.yml)\n[![OpenSSF Best Practices](https:\u002F\u002Fwww.bestpractices.dev\u002Fprojects\u002F8696\u002Fbadge)](https:\u002F\u002Fwww.bestpractices.dev\u002Fprojects\u002F8696)\n[![OpenSSF Scorecard](https:\u002F\u002Fapi.securityscorecards.dev\u002Fprojects\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics\u002Fbadge)](https:\u002F\u002Fapi.securityscorecards.dev\u002Fprojects\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics)\n\nkube-state-metrics (KSM) is a simple service that listens to the Kubernetes API\nserver and generates metrics about the state of the objects. (See examples in\nthe Metrics section below.) It is not focused on the health of the individual\nKubernetes components, but rather on the health of the various objects inside,\nsuch as deployments, nodes and pods.\n\nkube-state-metrics is about generating metrics from Kubernetes API objects\nwithout modification. This ensures that features provided by kube-state-metrics\nhave the same grade of stability as the Kubernetes API objects themselves. In\nturn, this means that kube-state-metrics in certain situations may not show the\nexact same values as kubectl, as kubectl applies certain heuristics to display\ncomprehensible messages. kube-state-metrics exposes raw data unmodified from the\nKubernetes API, this way users have all the data they require and perform\nheuristics as they see fit.\n\nThe metrics are exported on the HTTP endpoint `\u002Fmetrics` on the listening port\n(default 8080). They are served as plaintext. They are designed to be consumed\neither by Prometheus itself or by a scraper that is compatible with scraping a\nPrometheus client endpoint. You can also open `\u002Fmetrics` in a browser to see\nthe raw metrics. Note that the metrics exposed on the `\u002Fmetrics` endpoint\nreflect the current state of the Kubernetes cluster. When Kubernetes objects\nare deleted they are no longer visible on the `\u002Fmetrics` endpoint.\n\n> [!NOTE]\n> This README is generated from a [template](.\u002FREADME.md.tpl). Please make your changes there and run `make generate-template`.\n\n## Table of Contents\n\n* [Versioning](#versioning)\n  * [Kubernetes Version](#kubernetes-version)\n  * [Compatibility matrix](#compatibility-matrix)\n  * [Resource group version compatibility](#resource-group-version-compatibility)\n  * [Container Image](#container-image)\n* [Metrics Documentation](#metrics-documentation)\n  * [ECMAScript regular expression support for allow and deny lists](#ecmascript-regular-expression-support-for-allow-and-deny-lists)\n  * [Conflict resolution in label names](#conflict-resolution-in-label-names)\n* [Kube-state-metrics self metrics](#kube-state-metrics-self-metrics)\n* [kube-state-metrics vs. metrics-server](#kube-state-metrics-vs-metrics-server)\n* [Scaling kube-state-metrics](#scaling-kube-state-metrics)\n  * [Resource recommendation](#resource-recommendation)\n  * [Latency](#latency)\n  * [A note on costing](#a-note-on-costing)\n  * [Horizontal sharding](#horizontal-sharding)\n    * [Automated sharding](#automated-sharding)\n    * [Deployment sharding](#deployment-sharding)\n  * [Daemonset sharding for pod metrics](#daemonset-sharding-for-pod-metrics)\n  * [Resource filtering](#resource-filtering)\n* [Setup](#setup)\n  * [Building the Docker container](#building-the-docker-container)\n* [Usage](#usage)\n  * [Kubernetes Deployment](#kubernetes-deployment)\n  * [Limited privileges environment](#limited-privileges-environment)\n  * [Helm Chart](#helm-chart)\n  * [Development](#development)\n  * [Developer Contributions](#developer-contributions)\n  * [Community](#community)\n\n### Versioning\n\n#### Kubernetes Version\n\nkube-state-metrics uses [`client-go`](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fclient-go) to talk with\nKubernetes clusters. The supported Kubernetes cluster version is determined by\n[`client-go`](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fclient-go#compatibility-matrix).\nAll additional compatibility is only best effort, or happens to still\u002Falready be supported.\n\n#### Compatibility matrix\n\nAt most, 5 kube-state-metrics and 5 [kubernetes releases](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fkubernetes\u002Freleases) will be recorded below.\nGenerally, it is recommended to use the latest release of kube-state-metrics. If you run a very recent version of Kubernetes, you might want to use an unreleased version to have the full range of supported resources. If you run an older version of Kubernetes, you might need to run an older version in order to have full support for all resources. Be aware, that the maintainers will only support the latest release. Older versions might be supported by interested users of the community.\n\n| kube-state-metrics | Kubernetes client-go Version |\n|--------------------|:----------------------------:|\n| **v2.14.0**        | v1.31                        |\n| **v2.15.0**        | v1.32                        |\n| **v2.16.0**        | v1.32                        |\n| **v2.17.0**        | v1.33                        |\n| **v2.18.0**        | v1.34                        |\n| **main**           | v1.35                        |\n\n#### Resource group version compatibility\n\nResources in Kubernetes can evolve, i.e., the group version for a resource may change from alpha to beta and finally GA\nin different Kubernetes versions. For now, kube-state-metrics will only use the oldest API available in the latest\nrelease.\n\n#### Container Image\n\nThe latest container image can be found at:\n\n* `registry.k8s.io\u002Fkube-state-metrics\u002Fkube-state-metrics:v2.18.0` (arch: `amd64`, `arm`, `arm64`, `ppc64le` and `s390x`)\n* [Multi-architecture images](https:\u002F\u002Fexplore.ggcr.dev\u002F?image=registry.k8s.io%2Fkube-state-metrics%2Fkube-state-metrics:v2.18.0)\n\n### Metrics Documentation\n\nAny resources and metrics based on alpha Kubernetes APIs are excluded from any stability guarantee,\nwhich may be changed at any given release.\n\nSee the [`docs`](docs) directory for more information on the exposed metrics.\n\n#### Conflict resolution in label names\n\nThe `*_labels` family of metrics exposes Kubernetes labels as Prometheus labels.\nAs [Kubernetes](https:\u002F\u002Fkubernetes.io\u002Fdocs\u002Fconcepts\u002Foverview\u002Fworking-with-objects\u002Flabels\u002F#syntax-and-character-set)\nis more liberal than\n[Prometheus](https:\u002F\u002Fprometheus.io\u002Fdocs\u002Fconcepts\u002Fdata_model\u002F#metric-names-and-labels)\nin terms of allowed characters in label names,\nwe automatically convert unsupported characters to underscores.\nFor example, `app.kubernetes.io\u002Fname` becomes `label_app_kubernetes_io_name`.\n\nThis conversion can create conflicts when multiple Kubernetes labels like\n`foo-bar` and `foo_bar` would be converted to the same Prometheus label `label_foo_bar`.\n\nKube-state-metrics automatically adds a suffix `_conflictN` to resolve this conflict,\nso it converts the above labels to\n`label_foo_bar_conflict1` and `label_foo_bar_conflict2`.\n\nIf you'd like to have more control over how this conflict is resolved,\nyou might want to consider addressing this issue on a different level of the stack,\ne.g. by standardizing Kubernetes labels using an\n[Admission Webhook](https:\u002F\u002Fkubernetes.io\u002Fdocs\u002Freference\u002Faccess-authn-authz\u002Fextensible-admission-controllers\u002F)\nthat ensures that there are no possible conflicts.\n\n#### ECMAScript regular expression support for allow and deny lists\n\nStarting from [#2616](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fkube-state-metrics\u002Fpull\u002F2616\u002Ffiles), kube-state-metrics supports ECMAScript's `regexp` for allow and deny lists. This was incorporated as a workaround for the limitations of the `regexp` package in Go, which does not support lookarounds due to their non-linear time complexity. Please note that while lookarounds are now supported for allow and deny lists, regular expressions' evaluation time is capped at a minute to prevent performance issues.\n\n### Kube-state-metrics self metrics\n\nkube-state-metrics exposes its own general process metrics under `--telemetry-host` and `--telemetry-port` (default 8081).\n\nkube-state-metrics also exposes list and watch success and error metrics. These can be used to calculate the error rate of list or watch resources.\nIf you encounter those errors in the metrics, it is most likely a configuration or permission issue, and the next thing to investigate would be looking\nat the logs of kube-state-metrics.\n\nExample of the above mentioned metrics:\n\n```prometheus\nkube_state_metrics_list_total{resource=\"*v1.Node\",result=\"success\"} 1\nkube_state_metrics_list_total{resource=\"*v1.Node\",result=\"error\"} 52\nkube_state_metrics_watch_total{resource=\"*v1beta1.Ingress\",result=\"success\"} 1\n```\n\nkube-state-metrics also exposes some http request metrics, examples of those are:\n\n```prometheus\nhttp_request_duration_seconds_bucket{handler=\"metrics\",method=\"get\",le=\"2.5\"} 30\nhttp_request_duration_seconds_bucket{handler=\"metrics\",method=\"get\",le=\"5\"} 30\nhttp_request_duration_seconds_bucket{handler=\"metrics\",method=\"get\",le=\"10\"} 30\nhttp_request_duration_seconds_bucket{handler=\"metrics\",method=\"get\",le=\"+Inf\"} 30\nhttp_request_duration_seconds_sum{handler=\"metrics\",method=\"get\"} 0.021113919999999998\nhttp_request_duration_seconds_count{handler=\"metrics\",method=\"get\"} 30\n```\n\nkube-state-metrics also exposes build and configuration metrics:\n\n```prometheus\nkube_state_metrics_build_info{branch=\"main\",goversion=\"go1.15.3\",revision=\"6c9d775d\",version=\"v2.0.0-beta\"} 1\nkube_state_metrics_shard_ordinal{shard_ordinal=\"0\"} 0\nkube_state_metrics_total_shards 1\n```\n\n`kube_state_metrics_build_info` is used to expose version and other build information. For more usage about the info pattern,\nplease check this [blog post](https:\u002F\u002Fwww.robustperception.io\u002Fexposing-the-software-version-to-prometheus).\nSharding metrics expose `--shard` and `--total-shards` flags and can be used to validate\nrun-time configuration, see [`\u002Fexamples\u002Fprometheus-alerting-rules`](.\u002Fexamples\u002Fprometheus-alerting-rules).\n\nkube-state-metrics also exposes metrics about it config file and the Custom Resource State config file:\n\n```prometheus\nkube_state_metrics_config_hash{filename=\"crs.yml\",type=\"customresourceconfig\"} 2.38272279311849e+14\nkube_state_metrics_config_hash{filename=\"config.yml\",type=\"config\"} 2.65285922340846e+14\nkube_state_metrics_last_config_reload_success_timestamp_seconds{filename=\"crs.yml\",type=\"customresourceconfig\"} 1.6704882592037103e+09\nkube_state_metrics_last_config_reload_success_timestamp_seconds{filename=\"config.yml\",type=\"config\"} 1.6704882592035313e+09\nkube_state_metrics_last_config_reload_successful{filename=\"crs.yml\",type=\"customresourceconfig\"} 1\nkube_state_metrics_last_config_reload_successful{filename=\"config.yml\",type=\"config\"} 1\n```\n\n### kube-state-metrics vs. metrics-server\n\nThe [metrics-server](https:\u002F\u002Fgithub.com\u002Fkubernetes-incubator\u002Fmetrics-server)\nis a project that has been inspired by\n[Heapster](https:\u002F\u002Fgithub.com\u002Fkubernetes-retired\u002Fheapster) and is implemented\nto serve the goals of core metrics pipelines in [Kubernetes monitoring\narchitecture](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fdesign-proposals-archive\u002Fblob\u002Fmain\u002Finstrumentation\u002Fmonitoring_architecture.md).\nIt is a cluster level component which periodically scrapes metrics from all\nKubernetes nodes served by Kubelet through Metrics API. The metrics are\naggregated, stored in memory and served in [Metrics API\nformat](https:\u002F\u002Fgit.k8s.io\u002Fmetrics\u002Fpkg\u002Fapis\u002Fmetrics\u002Fv1alpha1\u002Ftypes.go). The\nmetrics-server stores the latest values only and is not responsible for\nforwarding metrics to third-party destinations.\n\nkube-state-metrics is focused on generating completely new metrics from\nKubernetes' object state (e.g. metrics based on deployments, replica sets,\netc.). It holds an entire snapshot of Kubernetes state in memory and\ncontinuously generates new metrics based off of it. And just like the\nmetrics-server it too is not responsible for exporting its metrics anywhere.\n\nHaving kube-state-metrics as a separate project also enables access to these\nmetrics from monitoring systems such as Prometheus.\n\n### Scaling kube-state-metrics\n\n#### Resource recommendation\n\nResource usage for kube-state-metrics changes with the Kubernetes objects (Pods\u002FNodes\u002FDeployments\u002FSecrets etc.) size of the cluster.\nTo some extent, the Kubernetes objects in a cluster are in direct proportion to the node number of the cluster.\n\nAs a general rule, you should allocate:\n\n* 250MiB memory\n* 0.1 cores\n\nNote that if CPU limits are set too low, kube-state-metrics' internal queues will not be able to be worked off quickly enough, resulting in increased memory consumption as the queue length grows. If you experience problems resulting from high memory allocation or CPU throttling, try increasing the CPU limits.\n\n#### Latency\n\nIn a 100 node cluster scaling test the latency numbers were as follows:\n\n```text\n\"Perc50\": 259615384 ns,\n\"Perc90\": 475000000 ns,\n\"Perc99\": 906666666 ns.\n```\n\n#### A note on costing\n\nBy default, kube-state-metrics exposes several metrics for events across your cluster. If you have a large number of frequently-updating resources on your cluster, you may find that a lot of data is ingested into these metrics. This can incur high costs on some cloud providers. Please take a moment to [configure what metrics you'd like to expose](docs\u002Fdeveloper\u002Fcli-arguments.md), as well as consult the documentation for your Kubernetes environment in order to avoid unexpectedly high costs.\n\n#### Horizontal sharding\n\nIn order to shard kube-state-metrics horizontally, some automated sharding capabilities have been implemented. It is configured with the following flags:\n\n* `--shard` (zero indexed)\n* `--total-shards`\n\nSharding is done by taking an md5 sum of the Kubernetes Object's UID and performing a modulo operation on it with the total number of shards. Each shard decides whether the object is handled by the respective instance of kube-state-metrics or not. Note that this means all instances of kube-state-metrics, even if sharded, will have the network traffic and the resource consumption for unmarshaling objects for all objects, not just the ones they are responsible for. To optimize this further, the Kubernetes API would need to support sharded list\u002Fwatch capabilities. In the optimal case, memory consumption for each shard will be 1\u002Fn compared to an unsharded setup. Typically, kube-state-metrics needs to be memory and latency optimized in order for it to return its metrics rather quickly to Prometheus. One way to reduce the latency between kube-state-metrics and the kube-apiserver is to run KSM with the `--use-apiserver-cache` flag. In addition to reducing the latency, this option will also lead to a reduction in the load on etcd.\n\nSharding should be used carefully and additional monitoring should be set up in order to ensure that sharding is set up and functioning as expected (eg. instances for each shard out of the total shards are configured).\n\n#### Automated sharding\n\nAutomatic sharding allows each shard to discover its nominal position when deployed in a StatefulSet which is useful for automatically configuring sharding. This is an experimental feature and may be broken or removed without notice.\n\nTo enable automated sharding, kube-state-metrics must be run by a `StatefulSet` and the pod name and namespace must be handed to the kube-state-metrics process via the `--pod` and `--pod-namespace` flags. Example manifests demonstrating the autosharding functionality can be found in [`\u002Fexamples\u002Fautosharding`](.\u002Fexamples\u002Fautosharding).\n\nThis way of deploying shards is useful when you want to manage KSM shards through a single Kubernetes resource (a single `StatefulSet` in this case) instead of having one `Deployment` per shard. The advantage can be especially significant when deploying a high number of shards.\n\nThe downside of using an auto-sharded setup comes from the rollout strategy supported by `StatefulSet`s. When managed by a `StatefulSet`, pods are replaced one at a time with each pod first getting terminated and then recreated. Besides such rollouts being slower, they will also lead to short downtime for each shard. If a Prometheus scrape happens during a rollout, it can miss some of the metrics exported by kube-state-metrics.\n\n#### Deployment sharding\n\nIf you prefer to manage shards as independent `Deployment` objects instead of using a single `StatefulSet`, you can use deployment-based sharding. In this model, each `Deployment` is configured with an explicit shard index using `--shard=\u003CN>` and the total number of shards using `--total-shards=\u003CN>`.\n\nExample manifests for deployment-based sharding are available in [`\u002Fexamples\u002Fdeploymentsharding`](.\u002Fexamples\u002Fdeploymentsharding).\n\nCompared to automated sharding, this approach:\n\n* Uses the standard `Deployment` rolling update behavior, which can reduce the risk of metric gaps during upgrades\n* Gives each shard a fixed, explicitly assigned shard index\n\nThe trade-offs are that:\n\n* You must manage each shard as a separate Kubernetes `Deployment`\n* You must keep the shard configuration consistent across all shard `Deployment` objects, such as the total shard count and shared settings\n  * This means scaling the number of shards requires redeploying all of them\n\n### Daemonset sharding for pod metrics\n\nFor pod metrics, they can be sharded per node with the following flag:\n\n* `--node=$(NODE_NAME)`\n\nEach kube-state-metrics pod uses FieldSelector (spec.nodeName) to watch\u002Flist pod metrics only on the same node.\n\nA daemonset kube-state-metrics example:\n\n```yaml\napiVersion: apps\u002Fv1\nkind: DaemonSet\nspec:\n  template:\n    spec:\n      containers:\n      - image: registry.k8s.io\u002Fkube-state-metrics\u002Fkube-state-metrics:IMAGE_TAG\n        name: kube-state-metrics\n        args:\n        - --resources=pods\n        - --node=$(NODE_NAME)\n        env:\n        - name: NODE_NAME\n          valueFrom:\n            fieldRef:\n              apiVersion: v1\n              fieldPath: spec.nodeName\n```\n\nTo track metrics for unassigned pods, you need to add an additional deployment and set `--track-unscheduled-pods`, as shown in the following example:\n\n```yaml\napiVersion: apps\u002Fv1\nkind: Deployment\nspec:\n  template:\n    spec:\n      containers:\n      - image: registry.k8s.io\u002Fkube-state-metrics\u002Fkube-state-metrics:IMAGE_TAG\n        name: kube-state-metrics\n        args:\n        - --resources=pods\n        - --track-unscheduled-pods\n```\n\nOther metrics can be sharded via [Horizontal sharding](#horizontal-sharding).\n\n#### Resource Filtering\n\nThe `\u002Fmetrics` endpoint supports filtering by resource type using the `resources` query parameter. This allows you to scrape only the metrics for specific Kubernetes resources, which can be useful for reducing the amount of data scraped or for creating separate scraping jobs for different resource types.\n\nExample:\n`curl 'http:\u002F\u002Flocalhost:8080\u002Fmetrics?resources=pods,secrets'`\n\nMultiple resources can be specified as a comma-separated list, or by providing the `resources` parameter multiple times.\n\nYou can also exclude specific resources using the `exclude_resources` query parameter. This is useful if you want to scrape all metrics except for a few specific ones.\n\nExample:\n`curl 'http:\u002F\u002Flocalhost:8080\u002Fmetrics?exclude_resources=pods'`\n\nIf both `resources` and `exclude_resources` are provided, the `resources` parameter acts as an allowlist, and `exclude_resources` acts as a denylist, filtering out any resources specified in the `exclude_resources` parameter from the allowed resources.\nThe exclude_resources takes precedence here and you can only filter on resources that are enabled in kube-state-metrics.\n\n### Setup\n\nInstall this project to your `$GOPATH` using `go get`:\n\n```bash\ngo get k8s.io\u002Fkube-state-metrics\u002Fv2\n```\n\n#### Building the Docker container\n\nSimply run the following command in this root folder, which will create a\nself-contained, statically-linked binary and build a Docker image:\n\n```bash\nmake container\n```\n\n### Usage\n\nSimply build and run kube-state-metrics inside a Kubernetes pod which has a\nservice account token that has read-only access to the Kubernetes cluster.\n\n#### For users of prometheus-operator\u002Fkube-prometheus stack\n\nThe ([`kube-prometheus`](https:\u002F\u002Fgithub.com\u002Fprometheus-operator\u002Fkube-prometheus\u002F)) stack installs kube-state-metrics as one of its [components](https:\u002F\u002Fgithub.com\u002Fprometheus-operator\u002Fkube-prometheus#kube-prometheus); you do not need to install kube-state-metrics if you're using the kube-prometheus stack.\n\nIf you want to revise the default configuration for kube-prometheus, for example to enable non-default metrics, have a look at [Customizing Kube-Prometheus](https:\u002F\u002Fgithub.com\u002Fprometheus-operator\u002Fkube-prometheus\u002Fblob\u002Fmain\u002Fdocs\u002Fcustomizing.md).\n\n#### Kubernetes Deployment\n\nTo deploy this project, you can simply run `kubectl apply -f examples\u002Fstandard` and a Kubernetes service and deployment will be created. (Note: Adjust the apiVersion of some resource if your kubernetes cluster's version is not 1.8+, check the yaml file for more information).\n\nTo have Prometheus discover kube-state-metrics instances it is advised to create a specific Prometheus scrape config for kube-state-metrics that picks up both metrics endpoints. Annotation based discovery is discouraged as only one of the endpoints would be able to be selected, plus kube-state-metrics in most cases has special authentication and authorization requirements as it essentially grants read access through the metrics endpoint to most information available to it.\n\n**Note:** Google Kubernetes Engine (GKE) Users - GKE has strict role permissions that will prevent the kube-state-metrics roles and role bindings from being created. To work around this, you can give your GCP identity the cluster-admin role by running the following one-liner:\n\n```bash\nkubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format='value(config.account)')\n```\n\nNote that your GCP identity is case sensitive but `gcloud info` as of Google Cloud SDK 221.0.0 is not. This means that if your IAM member contains capital letters, the above one-liner may not work for you. If you have 403 forbidden responses after running the above command and `kubectl apply -f examples\u002Fstandard`, check the IAM member associated with your account at \u003Chttps:\u002F\u002Fconsole.cloud.google.com\u002Fiam-admin\u002Fiam?project=PROJECT_ID>. If it contains capital letters, you may need to set the --user flag in the command above to the case-sensitive role listed at \u003Chttps:\u002F\u002Fconsole.cloud.google.com\u002Fiam-admin\u002Fiam?project=PROJECT_ID>.\n\nAfter running the above, if you see `Clusterrolebinding \"cluster-admin-binding\" created`, then you are able to continue with the setup of this service.\n\n#### Healthcheck Endpoints\n\nThe following healthcheck endpoints are available (`self` refers to the telemetry port, while `main` refers to the exposition port):\n\n* `\u002Fhealthz` (exposed on `main`): Returns a 200 status code if the application is running. We recommend to use this for the startup probe.\n* `\u002Flivez` (exposed on `main`): Returns a 200 status code if the application is not affected by an outage of the Kubernetes API Server. We recommend to using this for the liveness probe.\n* `\u002Freadyz` (exposed on `self`): Returns a 200 status code if the application is ready to accept requests and expose metrics. We recommend using this for the readiness probe.\n\nNote that it is discouraged to use the telemetry metrics endpoint for any probe when proxying the exposition data.\n\n#### Limited privileges environment\n\nIf you want to run kube-state-metrics in an environment where you don't have cluster-reader role, you can:\n\n* create a serviceaccount\n\n```yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n  name: kube-state-metrics\n  namespace: your-namespace-where-kube-state-metrics-will-deployed\n```\n\n* give it `view` privileges on specific namespaces (using roleBinding) (*note: you can add this roleBinding to all the NS you want your serviceaccount to access*)\n\n```yaml\napiVersion: rbac.authorization.k8s.io\u002Fv1\nkind: RoleBinding\nmetadata:\n  name: kube-state-metrics\n  namespace: project1\nroleRef:\n  apiGroup: rbac.authorization.k8s.io\n  kind: ClusterRole\n  name: view\nsubjects:\n  - kind: ServiceAccount\n    name: kube-state-metrics\n    namespace: your-namespace-where-kube-state-metrics-will-deployed\n```\n\n* then specify a set of namespaces (using the `--namespaces` option) and a set of kubernetes objects (using the `--resources`) that your serviceaccount has access to in the `kube-state-metrics` deployment configuration\n\n```yaml\nspec:\n  template:\n    spec:\n      containers:\n      - name: kube-state-metrics\n        args:\n          - '--resources=pods'\n          - '--namespaces=project1'\n```\n\nFor the full list of arguments available, see the documentation in [docs\u002Fdeveloper\u002Fcli-arguments.md](.\u002Fdocs\u002Fdeveloper\u002Fcli-arguments.md)\n\n#### Helm Chart\n\nStarting from the kube-state-metrics chart `v2.13.3` (kube-state-metrics image `v1.9.8`), the official [Helm chart](https:\u002F\u002Fartifacthub.io\u002Fpackages\u002Fhelm\u002Fprometheus-community\u002Fkube-state-metrics\u002F) is maintained in [prometheus-community\u002Fhelm-charts](https:\u002F\u002Fgithub.com\u002Fprometheus-community\u002Fhelm-charts\u002Ftree\u002Fmain\u002Fcharts\u002Fkube-state-metrics). Starting from kube-state-metrics chart `v3.0.0` only kube-state-metrics images of `v2.0.0 +` are supported.\n\n#### Development\n\nWhen developing, test a metric dump against your local Kubernetes cluster by running:\n\n> Users can override the apiserver address in KUBE-CONFIG file with `--apiserver` command line.\n\n```bash\ngo install\nkube-state-metrics --port=8080 --telemetry-port=8081 --kubeconfig=\u003CKUBE-CONFIG> --apiserver=\u003CAPISERVER>\n```\n\nThen curl the metrics endpoint\n\n```bash\ncurl localhost:8080\u002Fmetrics\n```\n\nTo run the e2e tests locally see the documentation in [tests\u002FREADME.md](.\u002Ftests\u002FREADME.md).\n\n#### Developer Contributions\n\nWhen developing, there are certain code patterns to follow to better your contributing experience and likelihood of e2e and other ci tests to pass. To learn more about them, see the documentation in [docs\u002Fdeveloper\u002Fguide.md](.\u002Fdocs\u002Fdeveloper\u002Fguide.md).\n\n#### Community\n\nThis project is sponsored by [SIG Instrumentation](https:\u002F\u002Fgithub.com\u002Fkubernetes\u002Fcommunity\u002Ftree\u002Fmaster\u002Fsig-instrumentation).\n\nThere is also a channel for [#kube-state-metrics](https:\u002F\u002Fkubernetes.slack.com\u002Farchives\u002FCJJ529RUY) on Kubernetes' Slack.\n\nYou can also join the SIG Instrumentation [mailing list](https:\u002F\u002Fgroups.google.com\u002Fforum\u002F#!forum\u002Fkubernetes-sig-instrumentation).\nThis will typically add invites for the following meetings to your calendar, in which topics around kube-state-metrics can be discussed.\n\n* Regular SIG Meeting: [Thursdays at 9:30 PT (Pacific Time)](https:\u002F\u002Fzoom.us\u002Fj\u002F5342565819?pwd=RlVsK21NVnR1dmE3SWZQSXhveHZPdz09) (biweekly). [Convert to your timezone](http:\u002F\u002Fwww.thetimezoneconverter.com\u002F?t=9:30&tz=PT%20%28Pacific%20Time%29).\n* Regular Triage Meeting: [Thursdays at 9:30 PT (Pacific Time)](https:\u002F\u002Fzoom.us\u002Fj\u002F5342565819?pwd=RlVsK21NVnR1dmE3SWZQSXhveHZPdz09) (biweekly - alternating with regular meeting). [Convert to your timezone](http:\u002F\u002Fwww.thetimezoneconverter.com\u002F?t=9:30&tz=PT%20%28Pacific%20Time%29).\n","kube-state-metrics 是一个附加代理，用于生成和暴露 Kubernetes 集群级别的指标。它通过监听 Kubernetes API 服务器来收集集群内对象（如部署、节点和 Pod）的状态信息，并将这些信息转化为可被 Prometheus 或其他兼容的监控工具抓取的指标数据。项目采用 Go 语言编写，确保了与 Kubernetes API 对象相同的稳定性级别，且不对其进行任何修改，从而提供最原始的数据供用户自定义处理逻辑。适用于需要对 Kubernetes 集群内部状态进行细粒度监控的场景，比如运维团队希望实时了解集群资源使用情况或应用程序运行状况时。","2026-06-11 03:25:45","top_topic"]