Custom Metrics Adapter Server Boilerplate

Purpose

This repository contains boilerplate code for setting up an implementation
of the Metrics APIs:

Custom metrics (k8s.io/metrics/pkg/apis/custom_metrics)
External metrics (k8s.io/metrics/pkg/apis/external_metrics)

It includes the necessary boilerplate for setting up an implementation
(generic API server setup, registration of resources, etc), plus an
implementation for testing that allows setting custom metric values over HTTP.

How to use this repository

This repository is designed to be used as a library. First, implement one
or more of the metrics provider interfaces in pkg/provider (for example,
CustomMetricsProvider), depending on which APIs you want to support.

Then, use the AdapterBase in pkg/cmd to initialize the necessary flags
and set up the API server, passing in your providers.

More information can be found in the getting started
guide, and the testing implementation can be
found in the test-adapter directory.

Prerequisites

Go: this library requires the same version of
Go as Kubernetes.

Test Adapter

There is a test adapter in this repository that can be used for testing
changes to the repository, as a mock implementation of the APIs for
automated unit tests, and also as an example implementation.

Note that this adapter should not be used for production. It’s for
writing automated e2e tests and serving as a sample only.

To build it:

# build the test-adapter container as $REGISTRY/k8s-test-metrics-adapter-amd64
export REGISTRY=<some-prefix>
make test-adapter-container

To test it locally, install kind,
then create a cluster, and start the tests:

kind create cluster
make test-kind

To test it in an arbitraty Kubernetes cluster:

# push the container up to a registry
docker push $REGISTRY/k8s-test-metrics-adapter-amd64
# launch the adapter using the test adapter deployment manifest
kubectl apply -f test-adapter-deploy/testing-adapter.yaml

When the deployment is ready, you can define new metrics on the test adapter
by querying the write endpoint:

# set up a proxy to the API server so we can access write endpoints
# of the testing adapter directly
kubectl proxy &
# write a sample metric -- the write paths match the same URL structure
# as the read paths, but at the /write-metrics base path.
# data needs to be in json, so we also need to set the content-type header
curl -X POST \
  -H 'Content-Type: application/json' \
  http://localhost:8001/api/v1/namespaces/custom-metrics/services/custom-metrics-apiserver:http/proxy/write-metrics/namespaces/default/services/kubernetes/test-metric \
  --data-raw '"300m"'

# you can pipe to `jq .` to pretty-print the output, if it's installed
# (otherwise, it's not necessary)
kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2" | jq .
# fetching certain custom metrics of namespaced resources
kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/default/services/kubernetes/test-metric" | jq .

If you wanted to target a simple nginx-deployment and then use this as an HPA scaler metric, something like this would work following the previous curl command:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-deployment
  namespace: default
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-deployment
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Object
    object:
      metric:
        name: test-metric
      describedObject:
        apiVersion: v1
        kind: Service
        name: kubernetes
      target:
        type: Value
        value: 300m

You can also query the external metrics:

kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1" | jq .
# fetching certain custom metrics of namespaced resources
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/default/my-external-metric" | jq .

Compatibility

The APIs in this repository follow the standard guarantees for Kubernetes
APIs, and will follow Kubernetes releases.

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the
community page.

You can reach the maintainers of this repository at:

Slack: channel #sig-instrumentation
Mailing List

Code of Conduct

Participation in the Kubernetes community is governed by the Kubernetes
Code of Conduct.

Contribution Guidelines

See CONTRIBUTING.md for more information.