Architecture overview¶

The GitHub runner deployment utilizes charms to manage the GitHub self-hosted runners. The GARM charm uses the GitHub Actions Runner Manager (GARM) to manage the runners, with the GARM configurator charm providing the configuration for the runners. In addition, the PostgreSQL charm is used to store the state of the GARM.

High-level overview of the deployment¶

        flowchart TD
  G(["GARM charm"]) --> PG[("PostgreSQL charm")]
  GC(["GARM configurator charm(s)"]) -->|many-to-one| G
  G -->|GitHub API| GH["GitHub"]
  G -->|OpenStack API| OS["OpenStack"]
  OS -->|Spawns multiple| RUN["Runner VMs"]
  RUN -->|callback| G
  COS(["OpenTelemetry Collector charm"]) -->|scrapes metrics| G

Multiple GARM configurator charms can provide configuration to a single GARM charm. Each GARM configurator charm manages the configuration for a single GitHub scaleset.

The diagram above contains the following components:

GARM charm: Operates a GitHub Actions Runner Manager (GARM) instance which manages GitHub Scalesets. The Scaleset is a GitHub feature for managing a set of Self-hosted runners.
GARM configurator charm: Provides configuration of a single GitHub scaleset to the GARM charm. Multiple GARM configurator charms can be integrated to a single GARM charm.
PostgreSQL charm: Provides a PostgreSQL database for the GARM charm to store its state.
OpenStack: The substrate where the runner VMs are spawned.
OpenTelemetry Collector charm: Scapes the metrics from the GARM charm and sends them to COS.

Ingress¶

The GARM charm services ingress using the REST API of GARM on the 8080 port. The spawned runners must call back to GARM on this port as part of the runner spawning process.

Observability¶

The GARM charm exposes Prometheus metrics that can be scraped by a monitoring stack and visualized in Grafana dashboards. The logs of the GARM charm are ingested by Loki to the dashboard.