Architecture

Overview #

Octorun is a Kubernetes native application means Octorun specifically designed to run on Kubernetes by extending the Kubernetes API using Custom Resources and Custom Controllers lately known as Operator Pattern.

Components #

Custom Resource Definitions (CRDs) #

A CustomResourceDefinition is a built-in resource that lets you extend the Kubernetes API. Octorun provides and relies on several CustomResourceDefinitions:

• Runner: represents a single Github self-hosted runner. It holds several fields for Github self-hosted runner creation as well as Pod specification. Runner designed to be immutable: once they are created, they are never updated (except for labels, annotations and status), only deleted.

• RunnerSet: provides a declarative Runners management such as deployment and scaling of a set of Runners with identical spec.

Controller #

Octorun controller implements Octorun Resources defined by Custom Resource Definitions. Octorun controller works similarly to Kubernetes controller but is only responsible for the Resources owned by Octorun. It does a control-loop logic that watches for create / update / delete events then make or request changes where needed that knowns as reconciliation.

Unlike Controllers in the ModelViewController pattern, Controllers in Kubernetes are run asynchronously after the Resources (Models) have been written to storage i.e. etcd.

Admission Webhook #

Octorun admission webhook is HTTP callbacks that receive admission requests, process it and return admission responses before Kubernetes API-Server store the Resouces in the etcd. Again Octorun Admission Webhook works similiarly to Kubernetes admission webhook. There are two types of admission webhooks: mutating admission webhook and validating admission webhook.

Github Webhook #

Octorun uses Github Webhook to listen for workflow_job events. The purpose is to inform the controller when owned runner is assigned a Workflow Job.

State Metrics #

Octorun state metrics is prometheus metric that export the state of Octorun Resources (i.e. Runner and RunnerSet). The implementation is similar to kube-state-metrics except octorun state metrics use prometheus library to provide the metrics instead of a custom HTTP response writer.

Octorun state metrics work well with Kubernetes prometheus-adapter to provide Kubernetes metrics series. The purpose is to support Kubernetes HorizonalPodAutoscaler for RunnerSet resource through Kubernetes custom.metrics.k8s.io API.