diff --git a/docs/changelog.md b/docs/changelog.md index d5abeab22..d7c95fb56 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -7,6 +7,7 @@ ### 2024-11-13 +- Added documentation for the reactive mode (howto and mongodb integration references). - Align the README with the one in https://github.com/canonical/is-charms-template-repo. ### 2024-10-24 diff --git a/docs/how-to/reactive.md b/docs/how-to/reactive.md new file mode 100644 index 000000000..9b1676b47 --- /dev/null +++ b/docs/how-to/reactive.md @@ -0,0 +1,108 @@ +# 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 only available for runners on OpenStack cloud and is +disabled by default and can be enabled by integrating the charm with a MongoDB database. + +## Requirements +For the purposes of this how-to-guide, we assume that you have a machine model (named "machine-model") +that can be used to deploy runners on an OpenStack cloud and [MongoDB](https://charmhub.io/mongodb), +and a k8s model (named "k8s-model") for the [webhook router](https://charmhub.io/github-runner-webhook-router). + +## 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 for reproducibility, you should adapt the revisions/channels to your needs. + +### GitHub Runner flavors + +For this how-to-guide, 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 .... +``` + +Please refer to [How to spawn OpenStack runner](how-to/openstack-runner.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 consume +``` + +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 organisation's 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 < 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. + +Switch to the k8s model and deploy the webhook router charm: + +```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= +juju consume +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. + + +In order to be reachable from GitHub, you need to make the webhook publicly available, you will need an ingress or the 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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 205865aa4..b11d83a63 100644 --- a/docs/index.md +++ b/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) diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index afcc79aad..30af02dea 100644 --- a/docs/reference/integrations.md +++ b/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 +``` \ No newline at end of file