Skip to content

Latest commit

 

History

History
169 lines (121 loc) · 8.37 KB

config_default.md

File metadata and controls

169 lines (121 loc) · 8.37 KB

The default config section

The default config section holds configuration options that don't need a category of their own, but are essential to the operation of the service. In this section we will detail each of the options available in the default section.

[default]
# This URL is used by instances to send back status messages as they install
# the github actions runner. Status messages can be seen by querying the
# runner status in garm.
# Note: If you're using a reverse proxy in front of your garm installation,
# this URL needs to point to the address of the reverse proxy. Using TLS is
# highly encouraged.
callback_url = "https://garm.example.com/api/v1/callbacks"

# This URL is used by instances to retrieve information they need to set themselves
# up. Access to this URL is granted using the same JWT token used to send back
# status updates. Once the instance transitions to "installed" or "failed" state,
# access to both the status and metadata endpoints is disabled.
# Note: If you're using a reverse proxy in front of your garm installation,
# this URL needs to point to the address of the reverse proxy. Using TLS is
# highly encouraged.
metadata_url = "https://garm.example.com/api/v1/metadata"

# Uncomment this line if you'd like to log to a file instead of standard output.
# log_file = "/tmp/runner-manager.log"

# 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

The callback_url option

Your runners will call back home with status updates as they install. Once they are set up, they will also send the GitHub agent ID they were allocated. You will need to configure the callback_url option in the garm server config. This URL needs to point to the following API endpoint:

POST /api/v1/callbacks/status

Example of a runner sending status updates:

garm-cli runner show garm-DvxiVAlfHeE7
+-----------------+------------------------------------------------------------------------------------+
| FIELD           | VALUE                                                                              |
+-----------------+------------------------------------------------------------------------------------+
| ID              | 16b96ba2-d406-45b8-ab66-b70be6237b4e                                               |
| Provider ID     | garm-DvxiVAlfHeE7                                                                  |
| Name            | garm-DvxiVAlfHeE7                                                                  |
| OS Type         | linux                                                                              |
| OS Architecture | amd64                                                                              |
| OS Name         | ubuntu                                                                             |
| OS Version      | jammy                                                                              |
| Status          | running                                                                            |
| Runner Status   | idle                                                                               |
| Pool ID         | 8ec34c1f-b053-4a5d-80d6-40afdfb389f9                                               |
| Addresses       | 10.198.117.120                                                                     |
| Status Updates  | 2023-07-08T06:26:46: runner registration token was retrieved                       |
|                 | 2023-07-08T06:26:46: using cached runner found in /opt/cache/actions-runner/latest |
|                 | 2023-07-08T06:26:50: configuring runner                                            |
|                 | 2023-07-08T06:26:56: runner successfully configured after 1 attempt(s)             |
|                 | 2023-07-08T06:26:56: installing runner service                                     |
|                 | 2023-07-08T06:26:56: starting service                                              |
|                 | 2023-07-08T06:26:57: runner successfully installed                                 |
+-----------------+------------------------------------------------------------------------------------+

This URL must be set and must be accessible by the instance. If you wish to restrict access to it, a reverse proxy can be configured to accept requests only from networks in which the runners garm manages will be spun up. This URL doesn't need to be globally accessible, it just needs to be accessible by the instances.

For example, in a scenario where you expose the API endpoint directly, this setting could look like the following:

callback_url = "https://garm.example.com/api/v1/callbacks"

Authentication is done using a short-lived JWT token, that gets generated for a particular instance that we are spinning up. That JWT token grants access to the instance to only update it's own status and to fetch metadata for itself. No other API endpoints will work with that JWT token. The validity of the token is equal to the pool bootstrap timeout value (default 20 minutes) plus the garm polling interval (5 minutes).

There is a sample nginx config in the testdata folder. Feel free to customize it whichever way you see fit.

The metadata_url option

The metadata URL is the base URL for any information an instance may need to fetch in order to finish setting itself up. As this URL may be placed behind a reverse proxy, you'll need to configure it in the garm config file. Ultimately this URL will need to point to the following garm API endpoint:

GET /api/v1/metadata

This URL needs to be accessible only by the instances garm sets up. This URL will not be used by anyone else. To configure it in garm add the following line in the [default] section of your garm config:

metadata_url = "https://garm.example.com/api/v1/metadata"

The debug_server option

GARM can optionally enable the golang profiling server. This is useful if you suspect garm may be bottlenecking in any way. To enable the profiling server, add the following section to the garm config:

[default]

debug_server = true

And restart garm. You can then use the following command to start profiling:

go tool pprof http://127.0.0.1:9997/debug/pprof/profile?seconds=120

Important note on profiling when behind a reverse proxy. The above command will hang for a fairly long time. Most reverse proxies will timeout after about 60 seconds. To avoid this, you should only profile on localhost by connecting directly to garm.

It's also advisable to exclude the debug server URLs from your reverse proxy and only make them available locally.

Now that the debug server is enabled, here is a blog post on how to profile golang applications: https://blog.golang.org/profiling-go-programs

The log_file option

By default, GARM logs everything to standard output.

You can optionally log to file by adding the following to your config file:

[default]
# Use this if you'd like to log to a file instead of standard output.
log_file = "/tmp/runner-manager.log"

Rotating log files

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:

[Service]
ExecReload=/bin/kill -HUP $MAINPID

Then you can simply:

systemctl reload garm

The enable_log_streamer option

This option allows you to stream garm logs directly to your terminal. Set this option to true, then you can use the following command to stream logs:

garm-cli debug-log

An important note on enabling this option when behind a reverse proxy. The log streamer uses websockets to stream logs to you. You will need to configure your reverse proxy to allow websocket connections. If you're using nginx, you will need to add the following to your nginx server config:

location /api/v1/ws {
    proxy_pass http://garm_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
}