From 8f5b7351622df4597d4623d5f9106909babfaf83 Mon Sep 17 00:00:00 2001 From: Sam Ghods Date: Fri, 6 May 2016 14:41:30 -0700 Subject: [PATCH] Update README.md --- README.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b290aa130e..38602cbbc1 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,45 @@ # Overview -kube-state-metrics generates metrics about the state of the object inside of a -Kubernetes cluster. It is not focused on the health of the Kubernetes -components individually, but rather on the health of the various objects -inside, such as deployments, nodes and pods. +kube-state-metrics 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. + +The metrics are exported through the [Prometheus golang +client](https://github.com/prometheus/client_golang) on the HTTP endpoint `/metrics` on +the listening port (default 80). They are served either as plaintext or +protobuf depending on the `Accept` header. 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. *Requires Kubernetes 1.2+* -# 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. - ## Metrics There are many more metrics we could report, but this first pass is focused on -those that could result in actionable alerts. Please contribute PR's for +those that could be used for actionable alerts. Please contribute PR's for additional metrics! ### WARNING: THESE METRIC/TAG NAMES ARE UNSTABLE AND MAY CHANGE IN A FUTURE RELEASE. -* nodes ready=<true|false> -* deployment_replicas name=<deployment-name> namespace=<deployment-namespace> -* deployment_replicas_available name=<deployment-name> namespace=<deployment-namespace> -* container_restarts name=<container-name> namespace=<pod-namespace> pod_name=<pod-name> +| Metric name | Labels/tags | +| ------------- | ------------- | +| nodes | ready=<true|false> | +| deployment_replicas | name=<deployment-name> namespace=<deployment-namespace> | +| deployment_replicas_available | name=<deployment-name> namespace=<deployment-namespace> | +| container_restarts | name=<container-name> namespace=<pod-namespace> pod_name=<pod-name> | + +# 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. # Development When developing, test a metric dump against your local Kubernetes cluster by running: ``` -go run main.go --apiserver=<APISERVER-HERE> --in-cluster=false --port=<APISERVER-PORT> --dry-run +go run main.go --apiserver= --in-cluster=false --port= --dry-run ```