Add initial documentation for reactive mode

docs/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### 2024-10-24
+
+- Added documentation for the reactive mode (howto and mongodb integration references).
+
 ### 2024-10-23
 
 - Fixed the wrong dateformat usage in the server uniqueness check.

docs/how-to/reactive.md

@@ -0,0 +1,112 @@
+# How to set up reactive spawning
+
+The charm provides an experimental feature to spawn runners reactively, depending on the jobs requested by GitHub.
+This feature is disabled by default and can be enabled by integrating the charm with a MongoDB database.
+
+## Requirements
+
+You need to deploy a webhook router, which listens for incoming jobs from GitHub, transforms them into
+labels and stores those labels in a MongoDB database. You can use the [GitHub Runner Webhook Router](https://charmhub.io/github-runner-webhook-router) for this purpose.
+The router and the GitHub runner charm must both be integrated with the same mongodb database.
+
+
+## Steps
+We are going to showcase the steps required to set up a reactive spawning environment with three runner flavors (large, large-arm, small) and a MongoDB database as a message queue.
+
+Note, that the specific revisions/channels in the steps are only marked here to have the howto reproducible, you should adapt these to your needs.
+
+We assume that you have a machine model (named "machine-model") for the runners and MongoDB, and a k8s model (named "k8s-model") for the webhook router.
+
+### GitHub Runner flavors
+
+For this howto, we decided to have deployed three runner flavors: `large`, `large-arm`, `small` . We need
+to deploy those with these names, to comply with the routing table defined below.
+
+```shell
+juju switch machine-model
+juju deploy github-runner large --channel latest/stable ....
+juju deploy github-runner large-arm --channel latest/stable ....
+juju deploy github-runner small --channel latest/stable ....
+```
+
+More steps are required if you are deploying runners on OpenStack cloud.
+
+Please refer to [How to spawn OpenStack runner](how-to/openstack-runner.md) or [How to run on LXD cloud](how-to/run-on-lxd.md)
+for more information on how to deploy the runners.
+
+### MongoDB
+
+You need to deploy a MongoDB application to use as a message queue. 
+You can choose to use the machine charm or the k8s charm version, although we recommend using
+the machine charm as the k8s version may not be reachable from outside the k8s cluster.
+
+```shell
+juju switch machine-model
+juju deploy mongodb --channel 6/edge --revision 188 
+juju expose mongodb
+juju offer mongodb:database
+juju grant <user-in-k8s-cloud> consume <offer-name>
+```
+
+Integrate with the runner charms
+
+```shell
+juju integrate large mongodb
+juju integrate large-arm mongodb
+juju integrate small mongodb
+```
+
+### Define a webhook in your organisation or repository where the self-hosted runners are registered.
+
+On your repository or organisations page on Github, you need to go to the settings and create a Webhook
+(e.g. https://github.com/canonical/github-runner-operator/settings/hooks). Please make sure to select
+
+- the Webhook url to be the URL of the webhook router
+- the content type `application/json`
+- the secret you defined in the webhook router (if you have so, which is recommended for security reasons)
+- the individual event "Workflow jobs" (and only this, as all other events will just be rejected by the webhook router)
+
+### Webhook router
+
+The webhook router is a k8s charm, therefore you need to deploy it on a k8s model.
+
+First, define a routing table to decide which labels should be routed to which runner flavor
+
+```shell
+cat <<EOF > routing_table.yaml 
+- large: [large, x64]
+- large-arm: [large, arm64]
+- small: [small]
+EOF
+```
+
+We decide to route all jobs with any label combination in the set `large,x64` to the large flavor, `large,arm64` to large-arm,
+and labels with `small` to small.
+This means, depending on which labels your users are setting in the workflow file, a different runner flavor will be used to
+execute the job.
+
+
+```shell
+juju switch k8s-model
+juju deploy github-runner-webhook-router --channel latest/edge --revision 30 --config flavours=@routing_table.yaml --config default-flavour=small --config webhook-secret=<your-secret>
+juju consume <offer-url>
+juju integrate github-runner-webhook-router mongodb
+```
+
+In this example we use "small" as the default flavor, to which all jobs with empty labels (or default labels such as `self-hosted`,`linux`) 
+are routed to.
+
+
+We also need to make the webhook publicly available, so you will probably need an ingress or traefik charm to expose the webhook router.
+
+```shell
+juju deploy nginx-ingress-integrator --channel latest/edge --revision 117 --config path-routes='/' --config service-hostname='githubu-runner-webhook-router.my.domain' --config trust=True
+juju integrate nginx-ingress-integrator github-runner-webhook-router
+```
+
+### COS integration
+You will probably also need some observability.
+The GitHub Runner and MongoDB machine charm provide COS integration via the `cos-agent` endpoint, and the
+Github Runner Webhook Router charm  provides the usual endpoints (`logging`, `metrics-endpoint`, `grafana-dashboard`). Please refer to
+[How to integrate with COS](how-to/integrate-with-cos.md) and [Canonical Observability Stack (COS) documentation](https://charmhub.io/topics/canonical-observability-stack) 
+for more information.

docs/index.md

@@ -61,6 +61,7 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
   1. [Comply with repository policies](how-to/repo-policy.md)
   1. [Run on LXD cloud](how-to/run-on-lxd.md)
   1. [Set base image](how-to/set-base-image.md)
+  1. [Set up reactive spawning](how-to/reactive.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [ARM64](reference/arm64.md)

docs/reference/integrations.md

@@ -12,3 +12,18 @@ Example debug-ssh integrate command:
 ```
 juju integrate github-runner tmate-ssh-server
 ```
+
+
+### mongodb
+
+_Interface_: mongodb_client   
+_Supported charms_: [mongodb](https://charmhub.io/mongodb), [mongodb-k8s](https://charmhub.io/mongodb-k8s)
+
+The mongodb integration provides the necessary information for the runner manager to access
+the mongodb database, which is required for the (experimental) reactive spawning feature.
+Integrating the charm with mongodb lets the charm automatically go into reactive mode.
+
+Example mongodb_client integrate command: 
+```
+juju integrate github-runner mongodb
+```