ARCHIVED AND READ ONLY - This project has been archived and marked as read only, it is no longer maintained.

You can still access the source code and run the examples, but no further code fixes will be made to this project.

Feel free to fork this if you want to continue working on it.

Custom Pod Autoscaler - Horizontal Pod Autoscaler (CPA-HPA)

This is the Horizontal Pod Autoscaler (HPA), modified to work as a Custom Pod Autoscaler (CPA). This project is designed to be a starting point to allow developers to quickly take a working Horizontal Pod Autoscaler and modify it as they need.

What is a Custom Pod Autoscaler?

A Custom Pod Autoscaler is a way to write custom logic into Kubernetes scalers. For more detailed overview, see the Custom Pod Autoscaler Framework.

How do I use this project?

If you want to deploy this CPA-HPA onto your cluster, you first need to install the Custom Pod Autoscaler Operator, follow the installation guide for instructions for installing the operator.

Overview of codebase

This project should be functionally similar/identical to the Kubernetes Horizontal Pod Autoscaler, with differences being that this is run as a CPA rather than a Kubernetes controller. The code is largely copied from the Kubernetes HPA and modified to work with the Custom Pod Autoscaler. Some restructuring of the architecture was required to fit with how a CPA operates, with the HPA logic now split into two distinct parts; metric gathering and evaluation.

Metric Gathering

The metric gathering stage takes in a resource to gather metrics for, and metric spec definitions for which metrics to gather. Using this information the metrics are gathered and calculated, from metrics APIs. These metrics are then serialised into JSON and output back to the CPA through stdout.

Evaluation

The evaluation stage takes in the metrics gathered by the metric gathering stage and makes a decision - how many replicas should the resource have. Once this decision has been made using data available the decision is serialised into JSON and output back to the CPA through stdout to do the actual scaling.

Configuration

There is some overlap in functionality between the the CPA and HPA, in this project precedence has been given to the CPA functionality. For example, Kubernetes HPAs have the ability to set minimum and maximum replica counts, this project removes those and instead relies on the CPA minimum and maximum replica counts. A Kubernetes HPA also contains a ScaleTargetRef for deciding which resource to target when scaling; for this project only the ScaleTargetRef of the CPA is used.

Deciding which metrics to use is done by using MetricSpecs, which are a key part of HPAs, and look like this:

- type: Resource
  resource:
    name: cpu
    target:
        type: Utilization
        averageUtilization: 50

To send these specs to the CPA-HPA, add a config option called metrics to the CPA, with a multiline string containing the metric list. For example:

config:
  - name: metrics
    value: |
      - type: Resource
        resource:
          name: cpu
          target:
            type: Utilization
            averageUtilization: 50

Example

There is an example of how to use the Custom Pod Autoscaler - Horizontal Pod Autoscaler in /example. The example has a simple deployment, taken from the Kubernetes Horizontal Pod Autoscaler walkthrough. The example also contains the YAML definition of the CPA-HPA.

More information

See the wiki for more information, such as guides and references.

Developing this project

Environment

Developing this project requires these dependencies:

• Go >= 1.17
• staticcheck == v0.3.0 (2022.1)
• Docker

To view the docs, you need Python 3 installed:

• Python >= 3.8

To view docs locally you need some Python dependencies, run:

pip install -r docs/requirements.txt

Commands

• make - builds the CPA-HPA binary.
• make docker - builds the CPA-HPA image.
• make lint - lints the code.
• make format - formats the code.
• make test - runs the project tests.
• make doc - hosts the documentation locally, at 127.0.0.1:8000.
• make coverage - shows the test coverage report.