From c2fa808cd36f553bc4b4f1ce73f46362b6a3b2f7 Mon Sep 17 00:00:00 2001 From: Gabriel Adrian Samfira Date: Thu, 6 Jul 2023 14:57:28 +0000 Subject: [PATCH] Update some docs Signed-off-by: Gabriel Adrian Samfira --- doc/database.md | 51 ++++++++++++----------------------- doc/logging.md | 19 ++++++++++--- doc/providers.md | 17 +++++++++--- doc/webhooks_and_callbacks.md | 8 +----- testdata/config.toml | 3 +++ 5 files changed, 51 insertions(+), 47 deletions(-) diff --git a/doc/database.md b/doc/database.md index 59204640..09c9be43 100644 --- a/doc/database.md +++ b/doc/database.md @@ -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" +``` diff --git a/doc/logging.md b/doc/logging.md index 02eb34c5..339b1e58 100644 --- a/doc/logging.md +++ b/doc/logging.md @@ -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 +``` \ No newline at end of file diff --git a/doc/providers.md b/doc/providers.md index d1042130..7a724ecc 100644 --- a/doc/providers.md +++ b/doc/providers.md @@ -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. diff --git a/doc/webhooks_and_callbacks.md b/doc/webhooks_and_callbacks.md index dfe1b3a1..0ff7555d 100644 --- a/doc/webhooks_and_callbacks.md +++ b/doc/webhooks_and_callbacks.md @@ -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: diff --git a/testdata/config.toml b/testdata/config.toml index 1182ad4a..0952ef34 100644 --- a/testdata/config.toml +++ b/testdata/config.toml @@ -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.