Runner configuration
- Runners are used to speed up builds and tests by evenly distributing pipeline load
- The server where Buddy On-Premises is first installed is the default runner (Primary).
- You can install more runners on other nodes for extra performance.
--yes
to the buddy
command, e.g. buddy --yes update-runner-config
.
Requirements
Resource | Requirement |
---|---|
CPU | 2.6 GHz |
Memory | 4 GB |
Root disk | 30 GB |
Installing runners
Launch the terminal on the server where you want to install the runner and run the commands below:
curl -sSL https://get.buddy.works | sh
buddy install-runner --token="$TOKEN" --standalone-host="$ADDRESS"
$$
Supported flags
Name | Description |
---|---|
--drain | Sets the runner to draining mode. |
--config | Fetches the data from a configuration file. Must have the path to the file set. |
--standalone-host | REQUIRED. The new IP address of the main instance. |
--token | REQUIRED. Overwrites the default authorization token. If not provided, Buddy will use the most recently provided token. |
--runner-memory | The amount of RAM in MB allocated for the runner service. |
--name | The name of the runner. Ignored if empty. |
--tag | The new tag applied to the runner. Ignored if empty. |
--memory | The new amount of RAM in MB that can be used by the build actions on the runner. Must be greater than 0 or will be ignored. |
--shm | The new amount of shared memory in MB. Must be greater than 0 or will be ignored. |
--concurrent | The new number of pipeline runners on the runner. Must be greater than 0 or will be ignored.) |
--internal-host | The IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server). Requires restart. |
--external-host | The external IP address of the server as seen by the primary server. Default value: the first detected external IP address. Requires restart. |
--runner-internal-port | The listening port of the runner. Default: 1090 . Can be changed if the port is taken. |
--runner-external-port | The external port of the runner to which Buddy On-Premises is connecting. Default: 1090 . Can be changed if the ports are mapped. |
--registry-internal-port | Registry listening port. Default: 1091 . Can be changed if the port is taken. |
--registry-external-port | Registry external port to which Buddy On-Premises is connecting Default: 1091 . Can be changed if the ports are mapped. |
Updating runners
To update the runner to the newest version of Buddy, sign in to the server that hosts the runner and run:
buddy update
$
Updating runner configuration
To update runner configuration (memory limits, tag, network settings, etc.), run this command on the runner server:
buddy update-runner-config
$
Supported flags
Name | Description |
---|---|
--drain | Sets the runner to draining mode. |
--config | Fetches the data from a configuration file. Must have the path to the file set. |
--standalone-host | The new IP address of the main instance. Requires restart. |
--token | Overwrites the default authorization token. If not provided, Buddy will use the most recently provided token. |
--runner-memory | The amount of RAM in MB allocated for the runner service. |
--name | The name of the runner. Ignored if empty. |
--tag | The new tag applied to the runner. Ignored if empty. |
--clear-tag | Clears the current tag applied to the runner. |
--cpus | The new number of CPUs that can be used by the build actions on the runner. Must be greater than 0 or will be ignored. |
--clear-cpus | Clears the limit on the number of CPUs available for the build actions on the runner. |
--memory | The new amount of RAM in MB that can be used by the build actions on the runner. Must be greater than 0 or will be ignored. |
--clear-memory | Clears the RAM limit for build actions on the runner. |
--shm | The new amount of shared memory in MB. Must be greater than 0 or will be ignored. |
--clear-memory | Clears the shared memory limit on the runner. |
--concurrent | The new number of pipeline runners on the runner. Must be greater than 0 or will be ignored.) |
--clear-concurrent | Clears the limit of pipeline runners on the runner. |
--internal-host | The IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server). Requires restart. |
--external-host | The external IP address of the server as seen by the primary server. Default value: the first detected external IP address. Requires restart. |
--runner-internal-port | The listening port of the runner. Default: 1090 . Requires restart. |
--runner-external-port | The external port of the runner to which Buddy On-Premises is connecting. Default: 1090 . Requires restart. |
--registry-internal-port | The listening port of the registry. Default: 1091 . Requires restart. |
--registry-external-port | The external port of the registry to which Buddy On-Premises is connecting. Default: 1091 . Requires restart. |
Scaling runners
Runner-specific variables provide information on average load, the number of free pipeline slots, IP address, and the number of runners, either with or without a specific tag. You can use them in custom scripts to calculate workload and launch or shut down extra nodes in your infrastructure.
Runner variables
Name | Description |
---|---|
BUDDY_RUNNERS | The JSON with information about all installed runners |
BUDDY_RUNNERS_CONCURRENT_SLOTS | The total number of pipeline slots across all runners |
BUDDY_RUNNERS_COUNT_${TAG} | The number of runners tagged with ${TAG} |
BUDDY_RUNNERS_COUNT_NOT_TAGGED | The number of untagged runners |
BUDDY_RUNNERS_FREE_SLOTS_${TAG} | The number of free pipeline slots on runners tagged with ${TAG} |
BUDDY_RUNNERS_FREE_SLOTS_NOT_TAGGED | The number of free pipeline slots on all untagged runners |
BUDDY_RUNNERS_AVG_LOAD_${TAG} | The average load from the last minute on all runners tagged with ${TAG} |
BUDDY_RUNNERS_AVG_LOAD_NOT_TAGGED | The average load from the last minute on all untagged runners |
BUDDY_RUNNER_ADDRESS_${TAG} | The list of IP addresses of runners tagged with ${TAG} |
BUDDY_RUNNER_ADDRESS_NOT_TAGGED | The list of IP addresses of untagged runners |
Removing runners
To delete a runner, run buddy delete-runner
or buddy uninstall
on the machine where the runner is installed.
Supported flags
Name | Description |
---|---|
--token | Overwrites the default authorization token. If not provided, Buddy will use the most recently provided token. |
Backup
Backing up runners follows the same process as backing up the main Buddy On-Premises instance.
Generating installation command
GUI
- Sign in to your Buddy On-Premises instance as admin.
- Go to the On-Premises Admin panel and switch to the Runners tab.
- Click Add new runner and copy the installation command.
- Proceed to the installation step to continue.
CLI
On the server with the main instance, run the following to generate the installation command and token and save it to an executable file:
buddy install-runner
$
Supported flags
Name | Description |
---|---|
--drain | Sets the runner to draining mode. |
--standalone-host | The IP address of the main instance. Must be provided during the installation or in the config file. |
--runner-memory | The amount of RAM in MB allocated for the runner service. |
--name | The name of the runner. |
--tag | The tag applied to the runner. Default value: empty (untagged). |
--cpus | The number of CPUs that cane be used by the build actions on the runner. Default value: 0 (unlimited). |
--memory | The amount of RAM in MB that can be used by the build actions on the runner. Default value: 0 (unlimited). |
--shm | The amount of shared memory in MB. Default value: 0 (unlimited). |
--concurrent | The number of concurrent pipelines running on the runner. Default value: 0 (unlimited). |
--internal-host | The IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server). |
--external-host | The external IP address of the server as seen by the primary server. Default value: the first detected external IP address. |
--runner-internal-port | The listening port of the runner. Default: 1090 . Can be changed if the port is taken. |
--runner-external-port | The external port of the runner to which Buddy On-Premises is connecting. Default: 1090 . Can be changed if the ports are mapped. |
--registry-internal-port | The listening port of the registry. Default: 1091 . Can be changed if the port is taken. |
--registry-external-port | The external port of the registry to which Buddy On-Premises is connecting. Default: 1091 . Can be changed if the ports are mapped. |
Runner authorization token
The authorization token is used to authenticate the runner in the main instance of Buddy On-Premises. To display the token run buddy configure
and select 15. (Runner token)
on the server with the main instance of Buddy On-Premises.
Regenerate
.
bash
buddy update-runner-config --token TOKEN_VALUE
Configuration file
Storing configuration in a file is a convenient way to set up new and update existing runners in non-interactive mode. To fetch the data from the config file, add the --config
flag to the command. For example:
buddy --yes update —-config="/home/buddy/config.yml"
$
What you need to know
- providing the
--config
flag requires an existing and parsable YAML file in the provided path - all fields are optional and can be skipped or empty
- all flags overwrite the values from the config file
Supported flags
Name | Type | Description |
---|---|---|
--drain | Boolean | Defines whether the runner is set to draining mode. |
--standalone-host | String | The IP address of the main instance. Cannot be empty. |
--token | String | The authorization token generated by the installation wizard. Can be regenerated with buddy configure |
--runner-memory | Number | The amount of RAM in MB allocated for the runner service. |
--tag | String | The tag applied to the runner. If set to empty (tag: "" ), the tag is cleared. |
--cpus | String | The number of CPUs that can be used by the build actions on the runner. Can be equal to 0 (unlimited) or greater. |
--memory | Number | The amount of RAM in MB that can be used by the build actions on the runner. Can be equal to 0 (unlimited) or greater. |
--concurrent | String | The number of concurrent pipeline runners on the runner. Can be equal to 0 (unlimited) or greater. |
--internal-host | The IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server). | |
--external-host | The external IP address of the server as seen by the primary server. Default value: the first detected external IP address. | |
--runner-internal-port | Number | The listening port of the runner. Can be changed if the port is taken. Must be > 0 or will be ignored. |
--runner-external-port | Number | The external port of the runner to which Buddy On-Premises is connecting. Can be changed if the ports are mapped. Must be > 0 or will be ignored |
--registry-internal-port | Number | The listening port of the registry. Can be changed if the port is taken. Must be > 0 or will be ignored. |
--registry-external-port | Number | The external port of the registry to which Buddy On-Premises is connecting. Can be changed if the ports are mapped. Must be > 0 or will be ignored. |
Example
standalone-host: "https://192.168.5.114"
name: "Runner-1"
tag: "tag-1"
cpus: 4
memory: 2048
shm: 256
concurrent: 4
token: 1a2b3c4d5e
internal-host: "0.0.0.0"
external-host: "3.3.3.3"
runner-internal-port: 1090
runner-external-port: 1090
registry-internal-port: 1091
registry-external-port: 1091
Management
CLI configuration options
Running buddy configure
on the runner, shows the options listed below. To configure an option, type the corresponding number and press Enter.
- Runner data path – allows to move the application data on the runner to a different partition or disk
IP & ports – allows to set IP & port addresses:
- internal IP – the internal IP address to which the runner is bound
- external host – the external IP address to which the primary instance is connecting to
- registry listening port (default
1090
) - runner listening port (default
1091
) - registry external port (default
1091
)
- Primary instance address – displays the IP address of the primary instance of Buddy.
- Runner token – displays the token used to authenticate in the primary instance of Buddy.
- Application memory management – changes the amount of RAM allocated to the Buddy application on the runner.
Checking runner status
You can view the list of connected runners and their status in the Runners tab of the on-premises admin panel. Possible statuses:
- 🟢 Running
- 🟠 Draining
- 🔘 Drained
- 🔴 Not running or wrong version
Runners tab
Locking
You can lock a runner and change its name in the runner settings.
Resources
The settings are also the place to adjust the resources consumed by the actions in the pipeline (vCPUs, RAM, and shared memory) and tag runners. If any pipeline is currently assigned to the runner, you will find it at the bottom of the page:
Runner settings
Offline runners
If a runner is offline or in a different version than the main instance, all pipeline executions end with an error. It is also impossible to browse the filesystems and view execution logs of the pipelines assigned to that runner.
You can remove an inactive runner from the runner list. When you remove a runner, pipelines assigned to that runner will be automatically assigned to a different runner on the next execution.
Last modified on May 17, 2024