d09f12dfd8
This branch adds the ability to forcefully remove a runner from GARM. When the operator wishes to manually remove a runner, the workflow is as follows: * Check that the runner exists in GitHub. If it does, attempt to remove it. An error here indicates that the runner may be processing a job. In this case, we don't continue and the operator gets immediate feedback from the API. * Mark the runner in the database as pending_delete * Allow the consolidate loop to reap it from the provider and remove it from the database. Removing the instance from the provider is async. If the provider errs out, GARM will keep trying to remove it in perpetuity until the provider succedes. In situations where the provider is misconfigured, this will never happen, leaving the instance in a permanent state of pending_delete. A provider may fail for various reasons. Either credentials have expired, the API endpoint has changed, the provider is misconfigured or the operator may just have removed it from the config before cleaning up the runners. While some cases are recoverable, some are not. We cannot have a situation in which we cannot clean resources in garm because of a misconfiguration. This change adds the pending_force_delete instance status. Instances marked with this status, will be removed from GARM even if the provider reports an error. The GARM cli has been modified to give new meaning to the --force-remove-runner option. This option in the CLI is no longer mandatory. Instead, setting it will mark the runner with the new pending_force_delete status. Omitting it will mark the runner with the old status of pending_delete. Fixes: #160 Signed-off-by: Gabriel Adrian Samfira <gsamfira@cloudbasesolutions.com> |
||
|---|---|---|
| .github/workflows | ||
| apiserver | ||
| auth | ||
| client | ||
| cmd | ||
| config | ||
| contrib | ||
| database | ||
| doc | ||
| internal/testing | ||
| metrics | ||
| params | ||
| runner | ||
| scripts | ||
| test/integration | ||
| testdata | ||
| util | ||
| vendor | ||
| websocket | ||
| .gitignore | ||
| Dockerfile | ||
| Dockerfile.build-static | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
GitHub Actions Runner Manager (GARM)
Welcome to GARM!
Garm enables you to create and automatically maintain pools of self-hosted GitHub runners, with autoscaling that can be used inside your github workflow runs.
The goal of GARM is to be simple to set up, simple to configure and simple to use. It is a single binary that can run on any GNU/Linux machine without any other requirements other than the providers it creates the runners in. It is intended to be easy to deploy in any environment and can create runners in any system you can write a provider for. There is no complicated setup process and no extremely complex concepts to understand. Once set up, it's meant to stay out of your way.
Garm supports creating pools on either GitHub itself or on your own deployment of GitHub Enterprise Server. For instructions on how to use GARM with GHE, see the credentials section of the documentation.
Join us on slack
Whether you're running into issues or just want to drop by and say "hi", feel free to join us on slack.
Installing
Check out the quickstart document for instructions on how to install GARM. If you'd like to build from source, check out the building from source document.
Installing external providers
External providers are binaries that GARM calls into to create runners in a particular IaaS. There are currently two external providers available:
Follow the instructions in the README of each provider to install them.
Configuration
The GARM configuration is a simple toml. The sample config file in the testdata folder is fairly well commented and should be enough to get you started. The configuration file is split into several sections, each of which is documented in its own page. The sections are:
Optimizing your runners
If you would like to optimize the startup time of new instance, take a look at the performance considerations page.
Write your own provider
The providers are interfaces between GARM and a particular IaaS in which we spin up GitHub Runners. These providers can be either native or external. The native providers are written in Go, and must implement the interface defined here. External providers can be written in any language, as they are in the form of an external executable that GARM calls into.
There is currently one native provider for LXD and two external providers for Openstack and Azure.
If you want to write your own provider, you can choose to write a native one, or implement an external one. The easiest one to write is probably an external provider. Please see the Writing an external provider document for details. Also, feel free to inspect the two available external providers in this repository.