k8shorizmetrics

README

k8shorizmetrics

k8shorizmetrics is a library that provides the internal workings of the Kubernetes Horizontal Pod Autoscaler (HPA) wrapped up in a simple API. The project allows querying metrics just as the HPA does, and also running the calculations to work out the target replica count that the HPA does.

Install

go get -u github.com/jthomperoo/k8shorizmetrics

Features

• Simple API, based directly on the code from the HPA, but detangled for ease of use.
• Dependent only on versioned and public Kubernetes Golang modules, allows easy install without replace directives.
• Splits the HPA into two parts, metric gathering and evaluation, only use what you need.
• Allows insights into how the HPA makes decisions.
• Supports scaling to and from 0.

Quick Start

The following is a simple program that can run inside a Kubernetes cluster that gets the CPU resource metrics for pods with the label run: php-apache.

package main

import (
	"log"
	"time"

	"github.com/jthomperoo/k8shorizmetrics"
	"github.com/jthomperoo/k8shorizmetrics/metricsclient"
	"github.com/jthomperoo/k8shorizmetrics/podsclient"
	"k8s.io/api/autoscaling/v2beta2"
	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/labels"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
)

func main() {
	// Kubernetes API setup
	clusterConfig, _ := rest.InClusterConfig()
	clientset, _ := kubernetes.NewForConfig(clusterConfig)
	// Metrics and pods clients setup
	metricsclient := metricsclient.NewClient(clusterConfig, clientset.Discovery())
	podsclient := &podsclient.OnDemandPodLister{Clientset: clientset}
	// HPA configuration options
	cpuInitializationPeriod := time.Duration(300) * time.Second
	initialReadinessDelay := time.Duration(30) * time.Second

	// Setup gatherer
	gather := k8shorizmetrics.NewGatherer(metricsclient, podsclient, cpuInitializationPeriod, initialReadinessDelay)

	// Target resource values
	namespace := "default"
	podSelector := labels.SelectorFromSet(labels.Set{
		"run": "php-apache",
	})

	// Metric spec to gather, CPU resource utilization
	spec := v2beta2.MetricSpec{
		Type: v2beta2.ResourceMetricSourceType,
		Resource: &v2beta2.ResourceMetricSource{
			Name: corev1.ResourceCPU,
			Target: v2beta2.MetricTarget{
				Type: v2beta2.UtilizationMetricType,
			},
		},
	}

	metric, _ := gather.GatherSingleMetric(spec, namespace, podSelector)

	for pod, podmetric := range metric.Resource.PodMetricsInfo {
		actualCPU := podmetric.Value
		requestedCPU := metric.Resource.Requests[pod]
		log.Printf("Pod: %s, CPU usage: %dm (%0.2f%% of requested)\n", pod, actualCPU, float64(actualCPU)/float64(requestedCPU)*100.0)
	}
}

Documentation

See the Go doc.

Examples

See the examples directory for some examples, cpuprint is a good start.

Developing and Contributing

See the contribution guidelines and code of conduct.

Documentation

Index

• type Evaluator
  • func NewEvaluator(tolerance float64) *Evaluator
  • func (e *Evaluator) Evaluate(gatheredMetrics []*metrics.Metric, currentReplicas int32) (int32, error)
  • func (e *Evaluator) EvaluateSingleMetric(gatheredMetric *metrics.Metric, currentReplicas int32) (int32, error)
  • func (e *Evaluator) EvaluateSingleMetricWithOptions(gatheredMetric *metrics.Metric, currentReplicas int32, tolerance float64) (int32, error)
  • func (e *Evaluator) EvaluateWithOptions(gatheredMetrics []*metrics.Metric, currentReplicas int32, tolerance float64) (int32, error)
• type ExternalEvaluater
• type ExternalGatherer
• type Gatherer
  • func NewGatherer(metricsclient metricsclient.Client, podlister corelisters.PodLister, ...) *Gatherer
  • func (c *Gatherer) Gather(specs []autoscalingv2.MetricSpec, namespace string, ...) ([]*metrics.Metric, error)
  • func (c *Gatherer) GatherSingleMetric(spec autoscalingv2.MetricSpec, namespace string, podSelector labels.Selector) (*metrics.Metric, error)
  • func (c *Gatherer) GatherSingleMetricWithOptions(spec autoscalingv2.MetricSpec, namespace string, podSelector labels.Selector, ...) (*metrics.Metric, error)
  • func (c *Gatherer) GatherWithOptions(specs []autoscalingv2.MetricSpec, namespace string, ...) ([]*metrics.Metric, error)
• type ObjectEvaluater
• type ObjectGatherer
• type PodsEvaluater
• type PodsGatherer
• type ResourceEvaluater
• type ResourceGatherer

Types

type Evaluator

type Evaluator struct {
	External  ExternalEvaluater
	Object    ObjectEvaluater
	Pods      PodsEvaluater
	Resource  ResourceEvaluater
	Tolerance float64
}

Evaluator provides functionality for deciding how many replicas a resource should have based on provided metrics.

func NewEvaluator

func NewEvaluator(tolerance float64) *Evaluator

NewEvaluator sets up an evaluate that can process external, object, pod and resource metrics

func (*Evaluator) Evaluate

func (e *Evaluator) Evaluate(gatheredMetrics []*metrics.Metric, currentReplicas int32) (int32, error)

func (*Evaluator) EvaluateSingleMetric

func (e *Evaluator) EvaluateSingleMetric(gatheredMetric *metrics.Metric, currentReplicas int32) (int32, error)

func (*Evaluator) EvaluateSingleMetricWithOptions

func (e *Evaluator) EvaluateSingleMetricWithOptions(gatheredMetric *metrics.Metric, currentReplicas int32, tolerance float64) (int32, error)

EvaluateSingleMetric returns the target replica count for a single metrics

func (*Evaluator) EvaluateWithOptions

func (e *Evaluator) EvaluateWithOptions(gatheredMetrics []*metrics.Metric, currentReplicas int32, tolerance float64) (int32, error)

Evaluate returns the target replica count for an array of multiple metrics

type ExternalEvaluater

type ExternalEvaluater interface {
	Evaluate(currentReplicas int32, gatheredMetric *metrics.Metric, tolerance float64) (int32, error)
}

ExternalEvaluater produces a replica count based on an external metric provided

type ExternalGatherer

type ExternalGatherer interface {
	Gather(metricName, namespace string, metricSelector *metav1.LabelSelector, podSelector labels.Selector) (*externalmetrics.Metric, error)
	GatherPerPod(metricName, namespace string, metricSelector *metav1.LabelSelector) (*externalmetrics.Metric, error)
}

ExternalGatherer allows retrieval of external metrics.

type Gatherer

type Gatherer struct {
	Resource                      ResourceGatherer
	Pods                          PodsGatherer
	Object                        ObjectGatherer
	External                      ExternalGatherer
	ScaleClient                   k8sscale.ScalesGetter
	CPUInitializationPeriod       time.Duration
	DelayOfInitialReadinessStatus time.Duration
}

Gatherer provides functionality for retrieving metrics on supplied metric specs.

func NewGatherer

func NewGatherer(
	metricsclient metricsclient.Client,
	podlister corelisters.PodLister,
	cpuInitializationPeriod time.Duration,
	delayOfInitialReadinessStatus time.Duration) *Gatherer

NewGatherer sets up a new Metric Gatherer

func (*Gatherer) Gather

func (c *Gatherer) Gather(specs []autoscalingv2.MetricSpec, namespace string, podSelector labels.Selector) ([]*metrics.Metric, error)

func (*Gatherer) GatherSingleMetric

func (c *Gatherer) GatherSingleMetric(spec autoscalingv2.MetricSpec, namespace string, podSelector labels.Selector) (*metrics.Metric, error)

func (*Gatherer) GatherSingleMetricWithOptions

func (c *Gatherer) GatherSingleMetricWithOptions(spec autoscalingv2.MetricSpec, namespace string, podSelector labels.Selector,
	cpuInitializationPeriod time.Duration, delayOfInitialReadinessStatus time.Duration) (*metrics.Metric, error)

GatherSingleMetric returns the metric gathered based on a single metric spec.

func (*Gatherer) GatherWithOptions

func (c *Gatherer) GatherWithOptions(specs []autoscalingv2.MetricSpec, namespace string, podSelector labels.Selector,
	cpuInitializationPeriod time.Duration, delayOfInitialReadinessStatus time.Duration) ([]*metrics.Metric, error)

Gather returns all of the metrics gathered based on the metric specs provided.

type ObjectEvaluater

type ObjectEvaluater interface {
	Evaluate(currentReplicas int32, gatheredMetric *metrics.Metric, tolerance float64) (int32, error)
}

ObjectEvaluater produces a replica count based on an object metric provided

type ObjectGatherer

type ObjectGatherer interface {
	Gather(metricName string, namespace string, objectRef *autoscalingv2.CrossVersionObjectReference, podSelector labels.Selector, metricSelector labels.Selector) (*objectmetrics.Metric, error)
	GatherPerPod(metricName string, namespace string, objectRef *autoscalingv2.CrossVersionObjectReference, metricSelector labels.Selector) (*objectmetrics.Metric, error)
}

ObjectGatherer allows retrieval of object metrics.

type PodsEvaluater

type PodsEvaluater interface {
	Evaluate(currentReplicas int32, gatheredMetric *metrics.Metric) int32
}

PodsEvaluater produces a replica count based on a pods metric provided

type PodsGatherer

type PodsGatherer interface {
	Gather(metricName string, namespace string, podSelector labels.Selector, metricSelector labels.Selector) (*podsmetrics.Metric, error)
}

PodsGatherer allows retrieval of pods metrics.

type ResourceEvaluater

type ResourceEvaluater interface {
	Evaluate(currentReplicas int32, gatheredMetric *metrics.Metric, tolerance float64) (int32, error)
}

ResourceEvaluater produces an evaluation based on a resource metric provided

type ResourceGatherer

type ResourceGatherer interface {
	Gather(resourceName corev1.ResourceName, namespace string, podSelector labels.Selector,
		cpuInitializationPeriod time.Duration, delayOfInitialReadinessStatus time.Duration) (*resourcemetrics.Metric, error)
	GatherRaw(resourceName corev1.ResourceName, namespace string, podSelector labels.Selector,
		cpuInitializationPeriod time.Duration, delayOfInitialReadinessStatus time.Duration) (*resourcemetrics.Metric, error)
}

ResourceGatherer allows retrieval of resource metrics.