From 6a99244f508ca25e122232bb352cc29a69231c6f Mon Sep 17 00:00:00 2001 From: Om Swastik Panda Date: Wed, 30 Jul 2025 14:48:33 +0530 Subject: [PATCH 1/4] added examples for cli flags usage --- docs/developer/cli-arguments.md | 92 +++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/docs/developer/cli-arguments.md b/docs/developer/cli-arguments.md index 887326b99..2a8f48161 100644 --- a/docs/developer/cli-arguments.md +++ b/docs/developer/cli-arguments.md @@ -92,3 +92,95 @@ Use "kube-state-metrics [command] --help" for more information about a command. ``` + +## Examples + +```bash +# Bool flag +kube-state-metrics --enable-gzip-encoding +``` + +```bash +# Int flag +kube-state-metrics --port=9090 +``` + +```bash +# String flag +kube-state-metrics --apiserver="https://my-apiserver:6443" +``` + +```bash +# Duration flags +kube-state-metrics --server-idle-timeout=2m --server-write-timeout=30s +``` + +```bash +# List flags (formatted as a single string) +kube-state-metrics \ + --metric-allowlist="kube_pod_info,kube_node_*" \ + --metric-denylist="kube_pod_labels_total,kube_service_info" \ + --metric-annotations-allowlist="namespaces=[kubernetes.io/team],pods=[owner]" \ + --metric-labels-allowlist="namespaces=[kubernetes.io/team],pods=[owner]" \ + --namespaces-denylist="default,kube-system" +``` +## Config-file support +You can provide a YAML config file using the `--config` flag instead of (or in addition to) command-line flags. Any flags passed on the command line will override values in the config file. + +Example `config.yaml`: +```yaml +port: 9090 +serverIdleTimeout: "2m" +metricAllowlist: + - kube_pod_info + - kube_node_* +``` + +Run with config file: +```bash +kube-state-metrics --config=config.yaml --port=8085 +``` + +## Mutual-exclusion of allowlists and denylists +For metrics, annotations, and labels, allowlists and denylists cannot be used together. If both are specified, the allowlist takes precedence and the denylist is ignored. + +## Kubernetes Deployment example +You can embed any of the flags in a Deployment manifest under `args:`: +```yaml +spec: + template: + spec: + containers: + - name: kube-state-metrics + args: + - "--metric-allowlist=kube_pod_info,kube_node_*" + - "--server-idle-timeout=2m" +``` + +## Experimental flags +The following flags are experimental and subject to change: +- `--auto-gomemlimit`, `--auto-gomemlimit-ratio` +- `--auth-filter` +- `--shard`, `--total-shards` +- `--track-unscheduled-pods` + +## Custom Resource State metrics +You can enable custom resource state metrics using: +```bash +kube-state-metrics --custom-resource-state-config-file=crs-config.yaml +``` +Example `crs-config.yaml`: +```yaml +resources: + pods: + state: + - Pending + - Running +``` + +## Auth-filter example +Protect the metrics endpoint with Kubernetes RBAC by enabling the auth filter and providing a kubeconfig: +```bash +kube-state-metrics --auth-filter --kubeconfig=/etc/kubernetes/kubeconfig +``` +Ensure the service account used has a Role or ClusterRole granting `get` on `metrics.k8s.io` in the desired namespace. From 2dc529de9e9c84e4805c3ec1a0f797ca6c8a8035 Mon Sep 17 00:00:00 2001 From: Om Swastik Panda Date: Fri, 1 Aug 2025 00:26:38 +0530 Subject: [PATCH 2/4] Update cli-arguments.md --- docs/developer/cli-arguments.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/developer/cli-arguments.md b/docs/developer/cli-arguments.md index 2a8f48161..ac6efd156 100644 --- a/docs/developer/cli-arguments.md +++ b/docs/developer/cli-arguments.md @@ -24,6 +24,7 @@ spec: [embedmd]:# (../../help.txt) + ```txt $ kube-state-metrics -h kube-state-metrics is a simple service that listens to the Kubernetes API server and generates metrics about the state of the objects. @@ -90,8 +91,6 @@ Flags: Use "kube-state-metrics [command] --help" for more information about a command. ``` - - ## Examples @@ -124,10 +123,13 @@ kube-state-metrics \ --metric-labels-allowlist="namespaces=[kubernetes.io/team],pods=[owner]" \ --namespaces-denylist="default,kube-system" ``` + ## Config-file support + You can provide a YAML config file using the `--config` flag instead of (or in addition to) command-line flags. Any flags passed on the command line will override values in the config file. Example `config.yaml`: + ```yaml port: 9090 serverIdleTimeout: "2m" @@ -137,15 +139,19 @@ metricAllowlist: ``` Run with config file: + ```bash kube-state-metrics --config=config.yaml --port=8085 ``` ## Mutual-exclusion of allowlists and denylists + For metrics, annotations, and labels, allowlists and denylists cannot be used together. If both are specified, the allowlist takes precedence and the denylist is ignored. ## Kubernetes Deployment example + You can embed any of the flags in a Deployment manifest under `args:`: + ```yaml spec: template: @@ -155,21 +161,27 @@ spec: args: - "--metric-allowlist=kube_pod_info,kube_node_*" - "--server-idle-timeout=2m" -``` +``` ## Experimental flags + The following flags are experimental and subject to change: -- `--auto-gomemlimit`, `--auto-gomemlimit-ratio` -- `--auth-filter` -- `--shard`, `--total-shards` -- `--track-unscheduled-pods` + +* `--auto-gomemlimit`, `--auto-gomemlimit-ratio` +* `--auth-filter` +* `--shard`, `--total-shards` +* `--track-unscheduled-pods` ## Custom Resource State metrics + You can enable custom resource state metrics using: + ```bash kube-state-metrics --custom-resource-state-config-file=crs-config.yaml ``` + Example `crs-config.yaml`: + ```yaml resources: pods: @@ -179,8 +191,12 @@ resources: ``` ## Auth-filter example + Protect the metrics endpoint with Kubernetes RBAC by enabling the auth filter and providing a kubeconfig: + ```bash kube-state-metrics --auth-filter --kubeconfig=/etc/kubernetes/kubeconfig ``` + Ensure the service account used has a Role or ClusterRole granting `get` on `metrics.k8s.io` in the desired namespace. + From 7e0eaa5aad84d410d62facbd7a2ebee1f23cea5f Mon Sep 17 00:00:00 2001 From: Om Swastik Panda Date: Fri, 1 Aug 2025 00:29:24 +0530 Subject: [PATCH 3/4] Update cli-arguments.md --- docs/developer/cli-arguments.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/developer/cli-arguments.md b/docs/developer/cli-arguments.md index ac6efd156..150154d62 100644 --- a/docs/developer/cli-arguments.md +++ b/docs/developer/cli-arguments.md @@ -124,7 +124,7 @@ kube-state-metrics \ --namespaces-denylist="default,kube-system" ``` -## Config-file support +### Config-file support You can provide a YAML config file using the `--config` flag instead of (or in addition to) command-line flags. Any flags passed on the command line will override values in the config file. @@ -144,11 +144,11 @@ Run with config file: kube-state-metrics --config=config.yaml --port=8085 ``` -## Mutual-exclusion of allowlists and denylists +### Mutual-exclusion of allowlists and denylists For metrics, annotations, and labels, allowlists and denylists cannot be used together. If both are specified, the allowlist takes precedence and the denylist is ignored. -## Kubernetes Deployment example +### Kubernetes Deployment example You can embed any of the flags in a Deployment manifest under `args:`: @@ -163,7 +163,7 @@ spec: - "--server-idle-timeout=2m" ``` -## Experimental flags +### Experimental flags The following flags are experimental and subject to change: @@ -172,7 +172,7 @@ The following flags are experimental and subject to change: * `--shard`, `--total-shards` * `--track-unscheduled-pods` -## Custom Resource State metrics +### Custom Resource State metrics You can enable custom resource state metrics using: @@ -190,7 +190,7 @@ resources: - Running ``` -## Auth-filter example +### Auth-filter example Protect the metrics endpoint with Kubernetes RBAC by enabling the auth filter and providing a kubeconfig: From b3abe2cb1006b777b56a50a0464dff50f6be3ff6 Mon Sep 17 00:00:00 2001 From: Om Swastik Panda Date: Mon, 4 Aug 2025 00:19:54 +0530 Subject: [PATCH 4/4] removed auth-filter example --- docs/developer/cli-arguments.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/developer/cli-arguments.md b/docs/developer/cli-arguments.md index 150154d62..d108a451f 100644 --- a/docs/developer/cli-arguments.md +++ b/docs/developer/cli-arguments.md @@ -189,14 +189,3 @@ resources: - Pending - Running ``` - -### Auth-filter example - -Protect the metrics endpoint with Kubernetes RBAC by enabling the auth filter and providing a kubeconfig: - -```bash -kube-state-metrics --auth-filter --kubeconfig=/etc/kubernetes/kubeconfig -``` - -Ensure the service account used has a Role or ClusterRole granting `get` on `metrics.k8s.io` in the desired namespace. -