DevFW-CICD/garm
15
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

Update some docs

Browse source 
Signed-off-by: Gabriel Adrian Samfira <gsamfira@cloudbasesolutions.com>
This commit is contained in:
Gabriel Adrian Samfira 2023-07-06 14:57:28 +00:00
parent 824a1efd78
commit c2fa808cd3
5 changed files with 51 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

51
doc/database.md
View file

@ -1,37 +1,20 @@
# Database configuration
Garm currently supports two database backends:
GARM currently supports SQLite3. The current implementation of GARM is single server, so it does not make much sense to enable anything else at the moment.
* SQLite3
* MySQL
You can choose either one of these. For most cases, ```SQLite3``` should do, but feel free to go with MySQL if you wish.
```toml
[database]
# Turn on/off debugging for database queries.
debug = false
# Database backend to use. Currently supported backends are:
# * sqlite3
# * mysql
backend = "sqlite3"
# the passphrase option is a temporary measure by which we encrypt the webhook
# secret that gets saved to the database, using AES256. In the future, secrets
# will be saved to something like Barbican or Vault, eliminating the need for
# this.
passphrase = "n<$n&P#L*TWqOh95_bN5J1r4mhxY7R84HZ%pvM#1vxJ<7~q%YVsCwU@Z60;7~Djo"
[database.mysql]
# If MySQL is used, these are the credentials and connection information used
# to connect to the server instance.
# database username
username = ""
# Database password
password = ""
# hostname to connect to
hostname = ""
# database name
database = ""
[database.sqlite3]
# Path on disk to the sqlite3 database file.
db_file = "/home/runner/file.db"
```
```toml
[database]
# Turn on/off debugging for database queries.
debug = false
# Database backend to use. Currently supported backends are:
# * sqlite3
backend = "sqlite3"
# the passphrase option is a temporary measure by which we encrypt the webhook
# secret that gets saved to the database, using AES256. In the future, secrets
# will be saved to something like Barbican or Vault, eliminating the need for
# this.
passphrase = "n<$n&P#L*TWqOh95_bN5J1r4mhxY7R84HZ%pvM#1vxJ<7~q%YVsCwU@Z60;7~Djo"
[database.sqlite3]
# Path on disk to the sqlite3 database file.
db_file = "/home/runner/garm.db"
```

19
doc/logging.md
View file

@ -1,8 +1,8 @@
# Logging
By default, GARM is logging only on standard output.
By default, GARM logs everything to standard output.
If you would like GARM to use a logging file instead, you can use the `log_file` configuration option:
You can optionally log to file by adding the following to your config file:
```toml
[default]
@ -12,6 +12,19 @@ log_file = "/tmp/runner-manager.log"
## Rotating log files
If GARM uses a log file, by default it will rotate it when it reaches 500MB or 28 days, whichever comes first.
GARM automatically rotates the log if it reaches 500 MB in size or 28 days, whichever comes first.
However, if you want to manually rotate the log file, you can send a `SIGHUP` signal to the GARM process.
You can add the following to your systemd unit file to enable `reload`:
```ini
[Service]
ExecReload=/bin/kill -HUP $MAINPID
```
Then you can simply:
```bash
systemctl reload garm
```

17
doc/providers.md
View file

@ -106,7 +106,7 @@ Image remotes in the ```garm``` config, is a map of strings to remote settings.
The external provider is a special kind of provider. It delegates the functionality needed to create the runners to external executables. These executables can be either binaries or scripts. As long as they adhere to the needed interface, they can be used to create runners in any target IaaS. This is identical to what ```containerd``` does with ```CNIs```.
There is currently one external provider for [OpenStack](https://www.openstack.org/) available in the [contrib folder of this repository](../contrib/providers.d/openstack). The provider is written in ```bash``` and it is just a sample. A production ready provider would need more error checking and idempotency, but it serves as an example of what can be done. As it stands, it is functional.
There are currently two external providers available in the [contrib folder of this repository](../contrib/providers.d/). The providers are written in ```bash``` and it are just samples. Production ready providers would need more error checking and idempotency, but they serve as an example of what can be done. As it stands, they are functional.
The configuration for an external provider is quite simple:
@ -127,13 +127,24 @@ provider_type = "external"
provider_executable = "/etc/garm/providers.d/openstack/garm-external-provider"
```
The external provider has three options:
The external provider has two options:
* ```provider_executable```
* ```config_file```
The ```provider_executable``` option is the absolute path to an executable that implements the provider logic. Garm will delegate all provider operations to this executable. This executable can be anything (bash, python, perl, go, etc). See [Writing an external provider](./external_provider.md) for more details.
The ```config_file``` option is a path on disk to an arbitrary file, that is passed to the external executable via the environment variable ```GARM_PROVIDER_CONFIG_FILE```. This file is only relevant to the external provider. Garm itself does not read it. In the case of the OpenStack provider, this file contains access information for an OpenStack cloud (what you would typically find in a ```keystonerc``` file) as well as some provider specific options like whether or not to boot from volume and which tenant network to use. You can check out the [sample config file](../contrib/providers.d/openstack/keystonerc) in this repository.
The ```config_file``` option is a path on disk to an arbitrary file, that is passed to the external executable via the environment variable ```GARM_PROVIDER_CONFIG_FILE```. This file is only relevant to the external provider. Garm itself does not read it. In the case of the sample OpenStack provider, this file contains access information for an OpenStack cloud (what you would typically find in a ```keystonerc``` file) as well as some provider specific options like whether or not to boot from volume and which tenant network to use. You can check out the [sample config file](../contrib/providers.d/openstack/keystonerc) in this repository.
If you want to implement an external provider, you can use this file for anything you need to pass into the binary when ```garm``` calls it to execute a particular operation.
### Available external providers
For non testing purposes, there are two external providers currently available:
* [OpenStack](https://github.com/cloudbase/garm-provider-openstack)
* [Azure](https://github.com/cloudbase/garm-provider-azure)
Details on how to install and configure them are available in their respective repositories.
If you wrote a provider and would like to add it to the above list, feel free to open a PR.

8
doc/webhooks_and_callbacks.md
View file

@ -1,12 +1,6 @@
# Webhooks
Garm is designed to auto-scale github runners based on a few simple rules:
* A minimum idle runner count can be set for a pool. Garm will attempt to maintain that minimum of idle runners, ready to be used by your workflows.
* A maximum number of runners for a pool. This is a hard limit of runners a pool will create, regardless of minimum idle runners.
* When a runner is scheduled by github, ```garm``` will automatically spin up a new runner to replace it, obeying the maximum hard limit defined.
To achieve this, ```garm``` relies on [GitHub Webhooks](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks). Webhooks allow ```garm``` to react to workflow events from your repository or organization.
Garm is designed to auto-scale github runners. To achieve this, ```garm``` relies on [GitHub Webhooks](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks). Webhooks allow ```garm``` to react to workflow events from your repository, organization or enterprise.
In your repository or organization, navigate to ```Settings --> Webhooks```. In the ```Payload URL``` field, enter the URL to the ```garm``` webhook endpoint. The ```garm``` API endpoint for webhooks is:

3
testdata/config.toml vendored
View file

@ -27,6 +27,9 @@ config_dir = "/etc/garm"
# Enable streaming logs via web sockets. Use garm-cli debug-log.
enable_log_streamer = false
# Enable the golang debug server. See the documentation in the "doc" folder for more information.
debug_server = false
[metrics]
# Toggle metrics. If set to false, the API endpoint for metrics collection will
# be disabled.