docs: Template the README file
This commit is contained in:
Manuel Rüger
parent
fa5eb67feb
commit
97b10ea5e7
|
|
@ -105,7 +105,7 @@ jobs:
|
|||
run: |
|
||||
make install-tools
|
||||
|
||||
- name: Check that all metrics are documented
|
||||
- name: Check that all metrics are documented and templates have no delta
|
||||
run: |
|
||||
make doccheck
|
||||
|
||||
|
|
|
|||
12
Makefile
12
Makefile
|
|
@ -50,7 +50,7 @@ lint-fix: fix-markdown-format
|
|||
golangci-lint run --fix -v
|
||||
|
||||
|
||||
doccheck: generate
|
||||
doccheck: generate validate-template
|
||||
@echo "- Checking if the generated documentation is up to date..."
|
||||
@git diff --exit-code
|
||||
@echo "- Checking if the documentation is in sync with the code..."
|
||||
|
|
@ -87,6 +87,12 @@ lint-markdown-format:
|
|||
fix-markdown-format:
|
||||
${DOCKER_CLI} run -v "${PWD}:/workdir" davidanson/markdownlint-cli2:v${MARKDOWNLINT_CLI2_VERSION} --fix --config .markdownlint-cli2.jsonc
|
||||
|
||||
generate-template:
|
||||
gomplate -d config=./data.yaml --file README.md.tpl > README.md
|
||||
|
||||
validate-template: generate-template
|
||||
git diff --no-ext-diff --quiet --exit-code README.md
|
||||
|
||||
# Runs benchmark tests on the current git ref and the last release and compares
|
||||
# the two.
|
||||
test-benchmark-compare:
|
||||
|
|
@ -129,7 +135,7 @@ clean:
|
|||
e2e:
|
||||
./tests/e2e.sh
|
||||
|
||||
generate: build-local
|
||||
generate: build-local generate-template
|
||||
@echo ">> generating docs"
|
||||
@./scripts/generate-help-text.sh
|
||||
embedmd -w `find . -path ./vendor -prune -o -name "*.md" -print`
|
||||
|
|
@ -172,4 +178,4 @@ install-promtool:
|
|||
@wget -qO- "https://github.com/prometheus/prometheus/releases/download/v${PROMETHEUS_VERSION}/prometheus-${PROMETHEUS_VERSION}.${OS}-${ARCH}.tar.gz" |\
|
||||
tar xvz --strip-components=1 prometheus-${PROMETHEUS_VERSION}.${OS}-${ARCH}/promtool
|
||||
|
||||
.PHONY: all build build-local all-push all-container container container-* do-push-* sub-push-* push push-multi-arch test-unit test-rules test-benchmark-compare clean e2e validate-modules shellcheck licensecheck lint lint-fix generate embedmd
|
||||
.PHONY: all build build-local all-push all-container container container-* do-push-* sub-push-* push push-multi-arch test-unit test-rules test-benchmark-compare clean e2e validate-modules shellcheck licensecheck lint lint-fix generate generate-template validate-template embedmd
|
||||
|
|
|
|||
|
|
@ -29,6 +29,9 @@ the raw metrics. Note that the metrics exposed on the `/metrics` endpoint
|
|||
reflect the current state of the Kubernetes cluster. When Kubernetes objects
|
||||
are deleted they are no longer visible on the `/metrics` endpoint.
|
||||
|
||||
> [!NOTE]
|
||||
> This README is generated from a [template](./README.md.tpl). Please make your changes there and run `make generate-template`.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Versioning](#versioning)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,415 @@
|
|||
# Overview
|
||||
|
||||
[](https://github.com/kubernetes/kube-state-metrics/actions)
|
||||
[](https://goreportcard.com/report/github.com/kubernetes/kube-state-metrics)
|
||||
[](https://pkg.go.dev/github.com/kubernetes/kube-state-metrics)
|
||||
[](https://github.com/kubernetes/kube-state-metrics/actions/workflows/govulncheck.yml)
|
||||
[](https://api.securityscorecards.dev/projects/github.com/kubernetes/kube-state-metrics)
|
||||
|
||||
kube-state-metrics (KSM) is a simple service that listens to the Kubernetes API
|
||||
server and generates metrics about the state of the objects. (See examples in
|
||||
the Metrics section below.) It is not focused on the health of the individual
|
||||
Kubernetes components, but rather on the health of the various objects inside,
|
||||
such as deployments, nodes and pods.
|
||||
|
||||
kube-state-metrics is about generating metrics from Kubernetes API objects
|
||||
without modification. This ensures that features provided by kube-state-metrics
|
||||
have the same grade of stability as the Kubernetes API objects themselves. In
|
||||
turn, this means that kube-state-metrics in certain situations may not show the
|
||||
exact same values as kubectl, as kubectl applies certain heuristics to display
|
||||
comprehensible messages. kube-state-metrics exposes raw data unmodified from the
|
||||
Kubernetes API, this way users have all the data they require and perform
|
||||
heuristics as they see fit.
|
||||
|
||||
The metrics are exported on the HTTP endpoint `/metrics` on the listening port
|
||||
(default 8080). They are served as plaintext. They are designed to be consumed
|
||||
either by Prometheus itself or by a scraper that is compatible with scraping a
|
||||
Prometheus client endpoint. You can also open `/metrics` in a browser to see
|
||||
the raw metrics. Note that the metrics exposed on the `/metrics` endpoint
|
||||
reflect the current state of the Kubernetes cluster. When Kubernetes objects
|
||||
are deleted they are no longer visible on the `/metrics` endpoint.
|
||||
|
||||
> [!NOTE]
|
||||
> This README is generated from a [template](./README.md.tpl). Please make your changes there and run `make generate-template`.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Versioning](#versioning)
|
||||
* [Kubernetes Version](#kubernetes-version)
|
||||
* [Compatibility matrix](#compatibility-matrix)
|
||||
* [Resource group version compatibility](#resource-group-version-compatibility)
|
||||
* [Container Image](#container-image)
|
||||
* [Metrics Documentation](#metrics-documentation)
|
||||
* [Conflict resolution in label names](#conflict-resolution-in-label-names)
|
||||
* [Kube-state-metrics self metrics](#kube-state-metrics-self-metrics)
|
||||
* [Resource recommendation](#resource-recommendation)
|
||||
* [Latency](#latency)
|
||||
* [A note on costing](#a-note-on-costing)
|
||||
* [kube-state-metrics vs. metrics-server](#kube-state-metrics-vs-metrics-server)
|
||||
* [Scaling kube-state-metrics](#scaling-kube-state-metrics)
|
||||
* [Resource recommendation](#resource-recommendation)
|
||||
* [Horizontal sharding](#horizontal-sharding)
|
||||
* [Automated sharding](#automated-sharding)
|
||||
* [Daemonset sharding for pod metrics](#daemonset-sharding-for-pod-metrics)
|
||||
* [Setup](#setup)
|
||||
* [Building the Docker container](#building-the-docker-container)
|
||||
* [Usage](#usage)
|
||||
* [Kubernetes Deployment](#kubernetes-deployment)
|
||||
* [Limited privileges environment](#limited-privileges-environment)
|
||||
* [Helm Chart](#helm-chart)
|
||||
* [Development](#development)
|
||||
* [Developer Contributions](#developer-contributions)
|
||||
|
||||
### Versioning
|
||||
|
||||
#### Kubernetes Version
|
||||
|
||||
kube-state-metrics uses [`client-go`](https://github.com/kubernetes/client-go) to talk with
|
||||
Kubernetes clusters. The supported Kubernetes cluster version is determined by `client-go`.
|
||||
The compatibility matrix for client-go and Kubernetes cluster can be found
|
||||
[here](https://github.com/kubernetes/client-go#compatibility-matrix).
|
||||
All additional compatibility is only best effort, or happens to still/already be supported.
|
||||
|
||||
#### Compatibility matrix
|
||||
|
||||
At most, 5 kube-state-metrics and 5 [kubernetes releases](https://github.com/kubernetes/kubernetes/releases) will be recorded below.
|
||||
Generally, 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.
|
||||
|
||||
| kube-state-metrics | Kubernetes client-go Version |
|
||||
|--------------------|:----------------------------:|
|
||||
{{ define "compat-matrix" -}}
|
||||
{{- range . -}}
|
||||
| **{{ .version }}**{{ strings.Repeat (conv.ToInt (math.Sub 15 (len .version))) " " }}| v{{ .kubernetes }} |
|
||||
{{ end -}}
|
||||
{{- end -}}
|
||||
{{ template "compat-matrix" (datasource "config").compat }}
|
||||
#### Resource group version compatibility
|
||||
|
||||
Resources in Kubernetes can evolve, i.e., the group version for a resource may change from alpha to beta and finally GA
|
||||
in different Kubernetes versions. For now, kube-state-metrics will only use the oldest API available in the latest
|
||||
release.
|
||||
|
||||
#### Container Image
|
||||
|
||||
The latest container image can be found at:
|
||||
{{ define "get-latest-release" -}}
|
||||
{{ (index . (math.Sub (len .) 2)).version -}}
|
||||
{{ end }}
|
||||
* `registry.k8s.io/kube-state-metrics/kube-state-metrics:{{ template "get-latest-release" (datasource "config").compat }}` (arch: `amd64`, `arm`, `arm64`, `ppc64le` and `s390x`)
|
||||
* View all multi-architecture images at [here](https://explore.ggcr.dev/?image=registry.k8s.io%2Fkube-state-metrics%2Fkube-state-metrics:{{ template "get-latest-release" (datasource "config").compat -}})
|
||||
|
||||
### Metrics Documentation
|
||||
|
||||
Any resources and metrics based on alpha Kubernetes APIs are excluded from any stability guarantee,
|
||||
which may be changed at any given release.
|
||||
|
||||
See the [`docs`](docs) directory for more information on the exposed metrics.
|
||||
|
||||
#### Conflict resolution in label names
|
||||
|
||||
The `*_labels` family of metrics exposes Kubernetes labels as Prometheus labels.
|
||||
As [Kubernetes](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)
|
||||
is more liberal than
|
||||
[Prometheus](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)
|
||||
in terms of allowed characters in label names,
|
||||
we automatically convert unsupported characters to underscores.
|
||||
For example, `app.kubernetes.io/name` becomes `label_app_kubernetes_io_name`.
|
||||
|
||||
This conversion can create conflicts when multiple Kubernetes labels like
|
||||
`foo-bar` and `foo_bar` would be converted to the same Prometheus label `label_foo_bar`.
|
||||
|
||||
Kube-state-metrics automatically adds a suffix `_conflictN` to resolve this conflict,
|
||||
so it converts the above labels to
|
||||
`label_foo_bar_conflict1` and `label_foo_bar_conflict2`.
|
||||
|
||||
If you'd like to have more control over how this conflict is resolved,
|
||||
you might want to consider addressing this issue on a different level of the stack,
|
||||
e.g. by standardizing Kubernetes labels using an
|
||||
[Admission Webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
|
||||
that ensures that there are no possible conflicts.
|
||||
|
||||
### Kube-state-metrics self metrics
|
||||
|
||||
kube-state-metrics exposes its own general process metrics under `--telemetry-host` and `--telemetry-port` (default 8081).
|
||||
|
||||
kube-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.
|
||||
If 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
|
||||
at the logs of kube-state-metrics.
|
||||
|
||||
Example of the above mentioned metrics:
|
||||
|
||||
```
|
||||
kube_state_metrics_list_total{resource="*v1.Node",result="success"} 1
|
||||
kube_state_metrics_list_total{resource="*v1.Node",result="error"} 52
|
||||
kube_state_metrics_watch_total{resource="*v1beta1.Ingress",result="success"} 1
|
||||
```
|
||||
|
||||
kube-state-metrics also exposes some http request metrics, examples of those are:
|
||||
|
||||
```
|
||||
http_request_duration_seconds_bucket{handler="metrics",method="get",le="2.5"} 30
|
||||
http_request_duration_seconds_bucket{handler="metrics",method="get",le="5"} 30
|
||||
http_request_duration_seconds_bucket{handler="metrics",method="get",le="10"} 30
|
||||
http_request_duration_seconds_bucket{handler="metrics",method="get",le="+Inf"} 30
|
||||
http_request_duration_seconds_sum{handler="metrics",method="get"} 0.021113919999999998
|
||||
http_request_duration_seconds_count{handler="metrics",method="get"} 30
|
||||
```
|
||||
|
||||
kube-state-metrics also exposes build and configuration metrics:
|
||||
|
||||
```
|
||||
kube_state_metrics_build_info{branch="main",goversion="go1.15.3",revision="6c9d775d",version="v2.0.0-beta"} 1
|
||||
kube_state_metrics_shard_ordinal{shard_ordinal="0"} 0
|
||||
kube_state_metrics_total_shards 1
|
||||
```
|
||||
|
||||
`kube_state_metrics_build_info` is used to expose version and other build information. For more usage about the info pattern,
|
||||
please check the blog post [here](https://www.robustperception.io/exposing-the-software-version-to-prometheus).
|
||||
Sharding metrics expose `--shard` and `--total-shards` flags and can be used to validate
|
||||
run-time configuration, see [`/examples/prometheus-alerting-rules`](./examples/prometheus-alerting-rules).
|
||||
|
||||
kube-state-metrics also exposes metrics about it config file and the Custom Resource State config file:
|
||||
|
||||
```
|
||||
kube_state_metrics_config_hash{filename="crs.yml",type="customresourceconfig"} 2.38272279311849e+14
|
||||
kube_state_metrics_config_hash{filename="config.yml",type="config"} 2.65285922340846e+14
|
||||
kube_state_metrics_last_config_reload_success_timestamp_seconds{filename="crs.yml",type="customresourceconfig"} 1.6704882592037103e+09
|
||||
kube_state_metrics_last_config_reload_success_timestamp_seconds{filename="config.yml",type="config"} 1.6704882592035313e+09
|
||||
kube_state_metrics_last_config_reload_successful{filename="crs.yml",type="customresourceconfig"} 1
|
||||
kube_state_metrics_last_config_reload_successful{filename="config.yml",type="config"} 1
|
||||
```
|
||||
|
||||
### Scaling kube-state-metrics
|
||||
|
||||
#### Resource recommendation
|
||||
|
||||
Resource usage for kube-state-metrics changes with the Kubernetes objects (Pods/Nodes/Deployments/Secrets etc.) size of the cluster.
|
||||
To some extent, the Kubernetes objects in a cluster are in direct proportion to the node number of the cluster.
|
||||
|
||||
As a general rule, you should allocate:
|
||||
|
||||
* 250MiB memory
|
||||
* 0.1 cores
|
||||
|
||||
Note 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.
|
||||
|
||||
### Latency
|
||||
|
||||
In a 100 node cluster scaling test the latency numbers were as follows:
|
||||
|
||||
```
|
||||
"Perc50": 259615384 ns,
|
||||
"Perc90": 475000000 ns,
|
||||
"Perc99": 906666666 ns.
|
||||
```
|
||||
|
||||
### A note on costing
|
||||
|
||||
By 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/cli-arguments.md), as well as consult the documentation for your Kubernetes environment in order to avoid unexpectedly high costs.
|
||||
|
||||
### kube-state-metrics vs. metrics-server
|
||||
|
||||
The [metrics-server](https://github.com/kubernetes-incubator/metrics-server)
|
||||
is a project that has been inspired by
|
||||
[Heapster](https://github.com/kubernetes-retired/heapster) and is implemented
|
||||
to serve the goals of core metrics pipelines in [Kubernetes monitoring
|
||||
architecture](https://github.com/kubernetes/design-proposals-archive/blob/main/instrumentation/monitoring_architecture.md).
|
||||
It is a cluster level component which periodically scrapes metrics from all
|
||||
Kubernetes nodes served by Kubelet through Metrics API. The metrics are
|
||||
aggregated, stored in memory and served in [Metrics API
|
||||
format](https://git.k8s.io/metrics/pkg/apis/metrics/v1alpha1/types.go). The
|
||||
metrics-server stores the latest values only and is not responsible for
|
||||
forwarding metrics to third-party destinations.
|
||||
|
||||
kube-state-metrics is focused on generating completely new metrics from
|
||||
Kubernetes' object state (e.g. metrics based on deployments, replica sets,
|
||||
etc.). It holds an entire snapshot of Kubernetes state in memory and
|
||||
continuously generates new metrics based off of it. And just like the
|
||||
metrics-server it too is not responsible for exporting its metrics anywhere.
|
||||
|
||||
Having kube-state-metrics as a separate project also enables access to these
|
||||
metrics from monitoring systems such as Prometheus.
|
||||
|
||||
### Horizontal sharding
|
||||
|
||||
In order to shard kube-state-metrics horizontally, some automated sharding capabilities have been implemented. It is configured with the following flags:
|
||||
|
||||
* `--shard` (zero indexed)
|
||||
* `--total-shards`
|
||||
|
||||
Sharding 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/watch capabilities. In the optimal case, memory consumption for each shard will be 1/n 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.
|
||||
|
||||
Sharding 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).
|
||||
|
||||
#### Automated sharding
|
||||
|
||||
Automatic 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.
|
||||
|
||||
To 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 [`/examples/autosharding`](./examples/autosharding).
|
||||
|
||||
This 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.
|
||||
|
||||
The 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.
|
||||
|
||||
### Daemonset sharding for pod metrics
|
||||
|
||||
For pod metrics, they can be sharded per node with the following flag:
|
||||
|
||||
* `--node=$(NODE_NAME)`
|
||||
|
||||
Each kube-state-metrics pod uses FieldSelector (spec.nodeName) to watch/list pod metrics only on the same node.
|
||||
|
||||
A daemonset kube-state-metrics example:
|
||||
|
||||
```
|
||||
apiVersion: apps/v1
|
||||
kind: DaemonSet
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG
|
||||
name: kube-state-metrics
|
||||
args:
|
||||
- --resource=pods
|
||||
- --node=$(NODE_NAME)
|
||||
env:
|
||||
- name: NODE_NAME
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
apiVersion: v1
|
||||
fieldPath: spec.nodeName
|
||||
```
|
||||
|
||||
To track metrics for unassigned pods, you need to add an additional deployment and set `--node=""`, as shown in the following example:
|
||||
|
||||
```
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG
|
||||
name: kube-state-metrics
|
||||
args:
|
||||
- --resources=pods
|
||||
- --node=""
|
||||
```
|
||||
|
||||
Other metrics can be sharded via [Horizontal sharding](#horizontal-sharding).
|
||||
|
||||
### Setup
|
||||
|
||||
Install this project to your `$GOPATH` using `go get`:
|
||||
|
||||
```
|
||||
go get k8s.io/kube-state-metrics
|
||||
```
|
||||
|
||||
#### Building the Docker container
|
||||
|
||||
Simply run the following command in this root folder, which will create a
|
||||
self-contained, statically-linked binary and build a Docker image:
|
||||
|
||||
```
|
||||
make container
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
Simply build and run kube-state-metrics inside a Kubernetes pod which has a
|
||||
service account token that has read-only access to the Kubernetes cluster.
|
||||
|
||||
#### For users of prometheus-operator/kube-prometheus stack
|
||||
|
||||
The ([`kube-prometheus`](https://github.com/prometheus-operator/kube-prometheus/)) stack installs kube-state-metrics as one of its [components](https://github.com/prometheus-operator/kube-prometheus#kube-prometheus); you do not need to install kube-state-metrics if you're using the kube-prometheus stack.
|
||||
|
||||
If 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://github.com/prometheus-operator/kube-prometheus/blob/main/docs/customizing.md).
|
||||
|
||||
#### Kubernetes Deployment
|
||||
|
||||
To deploy this project, you can simply run `kubectl apply -f examples/standard` 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).
|
||||
|
||||
To 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.
|
||||
|
||||
**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:
|
||||
|
||||
```
|
||||
kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format='value(config.account)')
|
||||
```
|
||||
|
||||
Note 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/standard`, check the IAM member associated with your account at <https://console.cloud.google.com/iam-admin/iam?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 <https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID>.
|
||||
|
||||
After running the above, if you see `Clusterrolebinding "cluster-admin-binding" created`, then you are able to continue with the setup of this service.
|
||||
|
||||
#### Limited privileges environment
|
||||
|
||||
If you want to run kube-state-metrics in an environment where you don't have cluster-reader role, you can:
|
||||
|
||||
* create a serviceaccount
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: kube-state-metrics
|
||||
namespace: your-namespace-where-kube-state-metrics-will-deployed
|
||||
```
|
||||
|
||||
* 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*)
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
name: kube-state-metrics
|
||||
namespace: project1
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: view
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: kube-state-metrics
|
||||
namespace: your-namespace-where-kube-state-metrics-will-deployed
|
||||
```
|
||||
|
||||
* 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
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: kube-state-metrics
|
||||
args:
|
||||
- '--resources=pods'
|
||||
- '--namespaces=project1'
|
||||
```
|
||||
|
||||
For the full list of arguments available, see the documentation in [docs/cli-arguments.md](./docs/cli-arguments.md)
|
||||
|
||||
#### Helm Chart
|
||||
|
||||
Starting from the kube-state-metrics chart `v2.13.3` (kube-state-metrics image `v1.9.8`), the official [Helm chart](https://artifacthub.io/packages/helm/prometheus-community/kube-state-metrics/) is maintained in [prometheus-community/helm-charts](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-state-metrics). Starting from kube-state-metrics chart `v3.0.0` only kube-state-metrics images of `v2.0.0 +` are supported.
|
||||
|
||||
#### Development
|
||||
|
||||
When developing, test a metric dump against your local Kubernetes cluster by
|
||||
running:
|
||||
|
||||
> Users can override the apiserver address in KUBE-CONFIG file with `--apiserver` command line.
|
||||
|
||||
go install
|
||||
kube-state-metrics --port=8080 --telemetry-port=8081 --kubeconfig=<KUBE-CONFIG> --apiserver=<APISERVER>
|
||||
|
||||
Then curl the metrics endpoint
|
||||
|
||||
curl localhost:8080/metrics
|
||||
|
||||
To run the e2e tests locally see the documentation in [tests/README.md](./tests/README.md).
|
||||
|
||||
#### Developer Contributions
|
||||
|
||||
When 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/developer/guide.md](./docs/developer/guide.md).
|
||||
|
|
@ -17,7 +17,8 @@ Maintaining the release branches for older minor releases happens on a best effo
|
|||
* Bump the version in the `VERSION` file in the root of the repository.
|
||||
* Run `make examples`, which will re-generate all example manifests to use the new version.
|
||||
* Make a PR to update:
|
||||
* [Compatibility matrix](README.md#compatibility-matrix)
|
||||
* Update the [[`data.yaml`](data.yaml)
|
||||
* Run `make generate`, which will update the compatibility matrix in README.md
|
||||
* Changelog entry
|
||||
* Only include user relevant changes
|
||||
* Entries in the [`CHANGELOG.md`](CHANGELOG.md) are meant to be in this order:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
# List at max 5 releases here + the main branch
|
||||
compat:
|
||||
- version: "v2.7.0"
|
||||
kubernetes: "1.25"
|
||||
- version: "v2.8.2"
|
||||
kubernetes: "1.26"
|
||||
- version: "v2.9.2"
|
||||
kubernetes: "1.26"
|
||||
- version: "v2.10.1"
|
||||
kubernetes: "1.27"
|
||||
- version: "v2.11.0"
|
||||
kubernetes: "1.28"
|
||||
- version: "main"
|
||||
kubernetes: "1.29"
|
||||
132
tools/go.mod
132
tools/go.mod
|
|
@ -1,27 +1,153 @@
|
|||
module k8s.io/kube-state-metrics/v2/tools
|
||||
|
||||
go 1.19
|
||||
go 1.21
|
||||
|
||||
require (
|
||||
github.com/brancz/gojsontoyaml v0.1.0
|
||||
github.com/campoy/embedmd v1.0.0
|
||||
github.com/google/go-jsonnet v0.20.0
|
||||
github.com/hairyhenderson/gomplate/v3 v3.11.7
|
||||
github.com/jsonnet-bundler/jsonnet-bundler v0.5.1
|
||||
golang.org/x/perf v0.0.0-20231127181059-b53752263861
|
||||
)
|
||||
|
||||
require (
|
||||
cloud.google.com/go v0.110.7 // indirect
|
||||
cloud.google.com/go/compute v1.23.0 // indirect
|
||||
cloud.google.com/go/compute/metadata v0.2.3 // indirect
|
||||
cloud.google.com/go/iam v1.1.1 // indirect
|
||||
cloud.google.com/go/storage v1.30.1 // indirect
|
||||
dario.cat/mergo v1.0.0 // indirect
|
||||
github.com/Masterminds/goutils v1.1.1 // indirect
|
||||
github.com/Microsoft/go-winio v0.6.1 // indirect
|
||||
github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371 // indirect
|
||||
github.com/Shopify/ejson v1.3.3 // indirect
|
||||
github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794 // indirect
|
||||
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751 // indirect
|
||||
github.com/alecthomas/units v0.0.0-20211218093645-b94a6e3cc137 // indirect
|
||||
github.com/apparentlymart/go-cidr v1.1.0 // indirect
|
||||
github.com/armon/go-metrics v0.4.0 // indirect
|
||||
github.com/armon/go-radix v1.0.0 // indirect
|
||||
github.com/aws/aws-sdk-go v1.44.206 // indirect
|
||||
github.com/aws/aws-sdk-go-v2 v1.16.4 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.4.1 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/config v1.15.9 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/credentials v1.12.4 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.12.5 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.11.14 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/internal/configsources v1.1.11 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.5 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/internal/ini v1.3.12 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/internal/v4a v1.0.2 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.9.1 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.1.6 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.5 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.13.5 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/s3 v1.26.10 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/sso v1.11.7 // indirect
|
||||
github.com/aws/aws-sdk-go-v2/service/sts v1.16.6 // indirect
|
||||
github.com/aws/smithy-go v1.11.2 // indirect
|
||||
github.com/cenkalti/backoff/v3 v3.2.2 // indirect
|
||||
github.com/cloudflare/circl v1.3.7 // indirect
|
||||
github.com/cyphar/filepath-securejoin v0.2.4 // indirect
|
||||
github.com/docker/libkv v0.2.2-0.20180912205406-458977154600 // indirect
|
||||
github.com/dustin/gojson v0.0.0-20160307161227-2e71ec9dd5ad // indirect
|
||||
github.com/emirpasic/gods v1.18.1 // indirect
|
||||
github.com/fatih/color v1.13.0 // indirect
|
||||
github.com/ghodss/yaml v1.0.0 // indirect
|
||||
github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
|
||||
github.com/go-git/go-billy/v5 v5.5.0 // indirect
|
||||
github.com/go-git/go-git/v5 v5.11.0 // indirect
|
||||
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
|
||||
github.com/golang/protobuf v1.5.3 // indirect
|
||||
github.com/golang/snappy v0.0.4 // indirect
|
||||
github.com/google/s2a-go v0.1.4 // indirect
|
||||
github.com/google/uuid v1.4.0 // indirect
|
||||
github.com/google/wire v0.5.0 // indirect
|
||||
github.com/googleapis/enterprise-certificate-proxy v0.2.3 // indirect
|
||||
github.com/googleapis/gax-go/v2 v2.11.0 // indirect
|
||||
github.com/gosimple/slug v1.12.0 // indirect
|
||||
github.com/gosimple/unidecode v1.0.1 // indirect
|
||||
github.com/hairyhenderson/go-fsimpl v0.0.0-20220529183339-9deae3e35047 // indirect
|
||||
github.com/hairyhenderson/toml v0.4.2-0.20210923231440-40456b8e66cf // indirect
|
||||
github.com/hairyhenderson/yaml v0.0.0-20220618171115-2d35fca545ce // indirect
|
||||
github.com/hashicorp/consul/api v1.13.0 // indirect
|
||||
github.com/hashicorp/errwrap v1.1.0 // indirect
|
||||
github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
|
||||
github.com/hashicorp/go-hclog v1.2.0 // indirect
|
||||
github.com/hashicorp/go-immutable-radix v1.3.1 // indirect
|
||||
github.com/hashicorp/go-multierror v1.1.1 // indirect
|
||||
github.com/hashicorp/go-plugin v1.4.4 // indirect
|
||||
github.com/hashicorp/go-retryablehttp v0.7.1 // indirect
|
||||
github.com/hashicorp/go-rootcerts v1.0.2 // indirect
|
||||
github.com/hashicorp/go-secure-stdlib/mlock v0.1.2 // indirect
|
||||
github.com/hashicorp/go-secure-stdlib/parseutil v0.1.5 // indirect
|
||||
github.com/hashicorp/go-secure-stdlib/strutil v0.1.2 // indirect
|
||||
github.com/hashicorp/go-sockaddr v1.0.2 // indirect
|
||||
github.com/hashicorp/go-uuid v1.0.3 // indirect
|
||||
github.com/hashicorp/go-version v1.5.0 // indirect
|
||||
github.com/hashicorp/golang-lru v0.5.4 // indirect
|
||||
github.com/hashicorp/hcl v1.0.0 // indirect
|
||||
github.com/hashicorp/serf v0.9.7 // indirect
|
||||
github.com/hashicorp/vault/api v1.6.0 // indirect
|
||||
github.com/hashicorp/vault/sdk v0.5.0 // indirect
|
||||
github.com/hashicorp/yamux v0.0.0-20211028200310-0bc27b27de87 // indirect
|
||||
github.com/inconshreveable/mousetrap v1.0.0 // indirect
|
||||
github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
|
||||
github.com/jmespath/go-jmespath v0.4.0 // indirect
|
||||
github.com/joho/godotenv v1.4.0 // indirect
|
||||
github.com/kevinburke/ssh_config v1.2.0 // indirect
|
||||
github.com/mattn/go-colorable v0.1.12 // indirect
|
||||
github.com/mattn/go-isatty v0.0.14 // indirect
|
||||
github.com/mitchellh/copystructure v1.2.0 // indirect
|
||||
github.com/mitchellh/go-homedir v1.1.0 // indirect
|
||||
github.com/mitchellh/go-testing-interface v1.14.1 // indirect
|
||||
github.com/mitchellh/mapstructure v1.5.0 // indirect
|
||||
github.com/mitchellh/reflectwalk v1.0.2 // indirect
|
||||
github.com/oklog/run v1.1.0 // indirect
|
||||
github.com/pierrec/lz4 v2.6.1+incompatible // indirect
|
||||
github.com/pjbgf/sha1cd v0.3.0 // indirect
|
||||
github.com/pkg/errors v0.9.1 // indirect
|
||||
github.com/pmezard/go-difflib v1.0.0 // indirect
|
||||
golang.org/x/sys v0.15.0 // indirect
|
||||
github.com/rs/zerolog v1.26.1 // indirect
|
||||
github.com/ryanuber/go-glob v1.0.0 // indirect
|
||||
github.com/sergi/go-diff v1.2.0 // indirect
|
||||
github.com/skeema/knownhosts v1.2.1 // indirect
|
||||
github.com/spf13/afero v1.8.2 // indirect
|
||||
github.com/spf13/cobra v1.4.0 // indirect
|
||||
github.com/spf13/pflag v1.0.5 // indirect
|
||||
github.com/ugorji/go/codec v1.2.7 // indirect
|
||||
github.com/xanzy/ssh-agent v0.3.3 // indirect
|
||||
github.com/zealic/xignore v0.3.3 // indirect
|
||||
go.etcd.io/bbolt v1.3.6 // indirect
|
||||
go.opencensus.io v0.24.0 // indirect
|
||||
go.uber.org/atomic v1.9.0 // indirect
|
||||
go4.org/intern v0.0.0-20230205224052-192e9f60865c // indirect
|
||||
go4.org/unsafe/assume-no-moving-gc v0.0.0-20230525183740-e7c30c78aeb2 // indirect
|
||||
gocloud.dev v0.25.1-0.20220408200107-09b10f7359f7 // indirect
|
||||
golang.org/x/crypto v0.18.0 // indirect
|
||||
golang.org/x/mod v0.12.0 // indirect
|
||||
golang.org/x/net v0.19.0 // indirect
|
||||
golang.org/x/oauth2 v0.15.0 // indirect
|
||||
golang.org/x/sync v0.3.0 // indirect
|
||||
golang.org/x/sys v0.16.0 // indirect
|
||||
golang.org/x/term v0.16.0 // indirect
|
||||
golang.org/x/text v0.14.0 // indirect
|
||||
golang.org/x/time v0.0.0-20220411224347-583f2d630306 // indirect
|
||||
golang.org/x/tools v0.13.0 // indirect
|
||||
golang.org/x/xerrors v0.0.0-20220907171357-04be3eba64a2 // indirect
|
||||
google.golang.org/api v0.126.0 // indirect
|
||||
google.golang.org/appengine v1.6.7 // indirect
|
||||
google.golang.org/genproto v0.0.0-20230822172742-b8732ec3820d // indirect
|
||||
google.golang.org/genproto/googleapis/api v0.0.0-20230822172742-b8732ec3820d // indirect
|
||||
google.golang.org/genproto/googleapis/rpc v0.0.0-20230822172742-b8732ec3820d // indirect
|
||||
google.golang.org/grpc v1.59.0 // indirect
|
||||
google.golang.org/protobuf v1.31.0 // indirect
|
||||
gopkg.in/alecthomas/kingpin.v2 v2.2.6 // indirect
|
||||
gopkg.in/square/go-jose.v2 v2.6.0 // indirect
|
||||
gopkg.in/warnings.v0 v0.1.2 // indirect
|
||||
gopkg.in/yaml.v2 v2.4.0 // indirect
|
||||
sigs.k8s.io/yaml v1.1.0 // indirect
|
||||
inet.af/netaddr v0.0.0-20230525184311-b8eac61e914a // indirect
|
||||
k8s.io/client-go v0.24.1 // indirect
|
||||
sigs.k8s.io/yaml v1.2.0 // indirect
|
||||
)
|
||||
|
|
|
|||
1472
tools/go.sum
1472
tools/go.sum
File diff suppressed because it is too large
Load Diff
|
|
@ -23,6 +23,7 @@ import (
|
|||
_ "github.com/brancz/gojsontoyaml"
|
||||
_ "github.com/campoy/embedmd"
|
||||
_ "github.com/google/go-jsonnet/cmd/jsonnet"
|
||||
_ "github.com/hairyhenderson/gomplate/v3/cmd/gomplate"
|
||||
_ "github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb"
|
||||
_ "golang.org/x/perf/cmd/benchstat"
|
||||
)
|
||||
|
|
|
|||
Loading…
Reference in New Issue