From f68a69461a70b64de0bf55ce59e73a47f2994101 Mon Sep 17 00:00:00 2001 From: Solly Ross Date: Tue, 6 Jun 2017 17:13:44 -0400 Subject: [PATCH] Add README The readme contains a basic description of configuration, as well as details on how underlying Prometheus metrics map to custom metrics API metrics. --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..bbadbfc7 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +Kubernetes Custom Metrics Adapter for Prometheus +================================================ + +This repository contains an implementation of the Kubernetes custom +metrics API +([custom-metrics.metrics.k8s.io/v1alpha1](https://github.com/kubernetes/metrics/tree/master/pkg/apis/custom_metrics)), +suitable for use with the autoscaling/v2 Horizontal Pod Autoscaler in +Kubernetes 1.6+. + +Configuration +------------- + +The adapter takes the standard Kubernetes generic API server arguments +(including those for authentication and authorization). By default, it +will attempt to using [Kubernetes in-cluster +config](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/#accessing-the-api-from-a-pod) +to connect to the cluster. + +It takes the following addition arguments specific to configuring how the +adapter talks to Prometheus and the main Kubernetes cluster: + +- `--lister-kubeconfig=`: This configures + how the adapter talks to a Kubernetes API server in order to list + objects when operating with label selectors. By default, it will use + in-cluster config. + +- `--metrics-relist-interval=`: This is the interval at which to + update the cache of available metrics from Prometheus. + +- `--rate-interval=`: This is the duration used when requesting + rate metrics from Prometheus. It *must* be larger than your Prometheus + collection interval. + +- `--prometheus-url=`: This is the URL used to connect to Prometheus. + It will eventually contain query parameters to configure the connection. + +Presentation +------------ + +The adapter gathers the names of available metrics from Prometheus at the +specified interval. Only metrics of the following forms are considered: + +- "container" metrics (cAdvisor container metrics): series with a name + starting with `container_`, as well as non-empty `namespace` and + `pod_name` labels. + +- "namespaced" metrics (metrics describing namespaced Kubernetes objects): + series with non-empty namespace labels (which don't start with + `container_`). + +*Note*: Currently, metrics on non-namespaced objects (besides namespaces +themselves) are not supported. + +Metrics in Prometheus are converted in the custom-metrics-API metrics as +follows: + +1. The metric name and type are decided: + - For container metrics, the `container_` prefix is removed + - If the metric has the `_total` suffix, it is marked as a counter + metric, and the suffix is removed + - If the metric has the `_seconds_total` suffix, it is marked as + a seconds counter metric, and the suffix is removed. + - If the metric has none of the above suffixes, is is marked as a gauge + metric, and the metric name is used as-is + +2. Relevant resources are associated with the metric: + - container metrics are associated with pods only + - for non-container metrics, each label on the series is considered. If + that label represents a resource (without the group) available on the + server, the metric is associated with that resource. A metric may be + associated with multiple resources. + +When retrieving counter and seconds-counter metrics, the adapter requests +the metrics as a rate over the configured amount of time. For metrics +with multiple associated resources, the adapter requests the metric +aggregated over all non-requested metrics. + +The adapter does not consider resources consumed by the "POD" container, +which exists as part of all Kubernetes pods running in Docker simply +supports the existance of the pod's shared network namespace.