Worker configuration

  • Workers 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 worker (Primary).
  • You can install more workers on other nodes for extra performance.

Requirements

ResourceRequirement
CPU2.6 GHz
Memory4 GB
Root disk30 GB
Workers require a Linux-type server (we recommend Ubuntu 20.04) with Docker and docker-compose installed to run.
The workers and the main Buddy instance must be able to connect to each other. You can configure the IP address and ports of the worker during the installation.
You cannot install a new worker on the server that runs the main Buddy On-Premises instance – this instance is a fully operational worker. Install new workers on different, compatible servers.

Installing workers

All commands listed in the article must be run as root.

Launch the terminal on the server where you want to install the worker and run the commands below:

curl -sSL https://get.buddy.works | sh 
buddy install-worker --token="$TOKEN" --standalone-host="$ADDRESS"
$$
You can generate the command with the token and address from the application GUI or the CLI.

Supported flags

NameDescription
--yesForces non-interactive configuration mode.
--drainSets the worker to draining mode.
--configFetches the data from a configuration file. Must have the path to the file set.
--standalone-hostREQUIRED. The new IP address of the main instance.
--tokenREQUIRED. Overwrites the default authorization token. If not provided, Buddy will use the most recently provided token.
--worker-memoryThe amount of RAM in MB allocated for the worker service.
--nameThe name of the worker. Ignored if empty.
--tagThe new tag applied to the worker. Ignored if empty.
--memoryThe new amount of RAM in MB that can be used by the build actions on the worker. Must be greater than 0 or will be ignored.
--shmThe new amount of shared memory in MB. Must be greater than 0 or will be ignored.
--concurrentThe new number of pipeline runners on the worker. Must be greater than 0 or will be ignored.)
--internal-hostThe IP address that will be bound by the worker. Default value: empty (binds to all IP's on the server). Requires restart.
--external-hostThe external IP address of the server as seen by the primary server. Default value: the first detected external IP address. Requires restart.
--runner-internal-portThe listening port of the runner. Default: 1090. Can be changed if the port is taken.
--runner-external-portThe external port of the runner to which Buddy On-Premises is connecting. Default: 1090. Can be changed if the ports are mapped.
--registry-internal-portRegistry listening port. Default: 1091. Can be changed if the port is taken.
--registry-external-portRegistry external port to which Buddy On-Premises is connecting Default: 1091. Can be changed if the ports are mapped.
Flags have higher priority than the data in the configuration file. For example, setting the memory limit with a parameter flag will overwrite the value from the config file.

Updating workers

To update the worker to the newest version of Buddy, sign in to the server that hosts the worker and run:

buddy update
$
The version of the worker and the main instance must be the same. If the versions are different, you can't assign new pipelines to the worker, and all pipelines assigned previously will fail with the "Wrong version" status.

Updating worker configuration

To update worker configuration (memory limits, tag, network settings, etc.), run this command on the worker server:

buddy update-worker-config
$

Supported flags

NameDescription
--yesForces non-interactive configuration mode.
--drainSets the worker to draining mode.
--configFetches the data from a configuration file. Must have the path to the file set.
--standalone-hostThe new IP address of the main instance. Requires restart.
--tokenOverwrites the default authorization token. If not provided, Buddy will use the most recently provided token.
--worker-memoryThe amount of RAM in MB allocated for the worker service.
--nameThe name of the worker. Ignored if empty.
--tagThe new tag applied to the worker. Ignored if empty.
--clear-tagClears the current tag applied to the worker.
--cpusThe new number of CPUs that can be used by the build actions on the worker. Must be greater than 0 or will be ignored.
--clear-cpusClears the limit on the number of CPUs available for the build actions on the worker.
--memoryThe new amount of RAM in MB that can be used by the build actions on the worker. Must be greater than 0 or will be ignored.
--clear-memoryClears the RAM limit for build actions on the worker.
--shmThe new amount of shared memory in MB. Must be greater than 0 or will be ignored.
--clear-memoryClears the shared memory limit on the worker.
--concurrentThe new number of pipeline runners on the worker. Must be greater than 0 or will be ignored.)
--clear-concurrentClears the limit of pipeline runners on the worker.
--internal-hostThe IP address that will be bound by the worker. Default value: empty (binds to all IP's on the server). Requires restart.
--external-hostThe external IP address of the server as seen by the primary server. Default value: the first detected external IP address. Requires restart.
--runner-internal-portThe listening port of the runner. Default: 1090. Requires restart.
--runner-external-portThe external port of the runner to which Buddy On-Premises is connecting. Default: 1090. Requires restart.
--registry-internal-portThe listening port of the registry. Default: 1091. Requires restart.
--registry-external-portThe external port of the registry to which Buddy On-Premises is connecting. Default: 1091. Requires restart.
Flags have higher priority than the data in the configuration file. For example, setting the memory limit with a parameter flag will overwrite the value from the config file.

Scaling workers

Worker-specific variables provide information on average load, the number of free pipeline slots, IP address, and the number of workers, 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.

Here you will find an example guide how to use worker variables in Terraform to scale Buddy on AWS: buddy.works/guides/worker-scaling

Worker variables

NameDescription
BUDDY_WORKERSThe JSON with information about all installed workers
BUDDY_WORKERS_CONCURRENT_SLOTSThe total number of pipeline slots across all workers
BUDDY_WORKERS_COUNT_${TAG}The number of workers tagged with ${TAG}
BUDDY_WORKERS_COUNT_NOT_TAGGEDThe number of untagged workers
BUDDY_WORKERS_FREE_SLOTS_${TAG}The number of free pipeline slots on workers tagged with ${TAG}
BUDDY_WORKERS_FREE_SLOTS_NOT_TAGGEDThe number of free pipeline slots on all untagged workers
BUDDY_WORKERS_AVG_LOAD_${TAG}The average load from the last minute on all workers tagged with ${TAG}
BUDDY_WORKERS_AVG_LOAD_NOT_TAGGEDThe average load from the last minute on all untagged workers
BUDDY_WORKER_ADDRESS_${TAG}The list of IP addresses of workers tagged with ${TAG}
BUDDY_WORKER_ADDRESS_NOT_TAGGEDThe list of IP addresses of untagged workers

Removing workers

To delete a worker, run buddy delete-worker or buddy uninstall on the machine where the worker is installed.

Supported flags

NameDescription
--yesForces non-interactive configuration mode.
 --tokenOverwrites the default authorization token. If not provided, Buddy will use the most recently provided token.

Backup

Backing up workers follows the same process as backing up the main Buddy On-Premises instance.

Generating installation command

GUI

  1. Sign in to your Buddy On-Premises instance as admin.
  2. Go to the On-Premises Admin panel and switch to the Workers tab.
  3. Click Add new worker and copy the installation command.
  4. 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-worker
$

Supported flags

NameDescription
--yesForces non-interactive configuration mode.
--drainSets the worker to draining mode.
--standalone-hostThe IP address of the main instance. Must be provided during the installation or in the config file.
--worker-memoryThe amount of RAM in MB allocated for the worker service.
--nameThe name of the worker.
--tagThe tag applied to the worker. Default value: empty (untagged).
--cpusThe number of CPUs that cane be used by the build actions on the worker. Default value: 0 (unlimited).
--memoryThe amount of RAM in MB that can be used by the build actions on the worker. Default value: 0 (unlimited).
--shmThe amount of shared memory in MB. Default value: 0 (unlimited).
--concurrentThe number of concurrent pipelines running on the worker. Default value: 0 (unlimited).
--internal-hostThe IP address that will be bound by the worker. Default value: empty (binds to all IP's on the server).
--external-hostThe external IP address of the server as seen by the primary server. Default value: the first detected external IP address.
--runner-internal-portThe listening port of the runner. Default: 1090. Can be changed if the port is taken.
--runner-external-portThe external port of the runner to which Buddy On-Premises is connecting. Default: 1090. Can be changed if the ports are mapped.
--registry-internal-portThe listening port of the registry. Default: 1091. Can be changed if the port is taken.
--registry-external-portThe external port of the registry to which Buddy On-Premises is connecting. Default: 1091. Can be changed if the ports are mapped.

Worker authorization token

The authorization token is used to authenticate the worker in the main instance of Buddy On-Premises. To display the token run buddy configure and select 15. (Worker token) on the server with the main instance of Buddy On-Premises.

The token is long-lived and the same for all workers in your Buddy On-Premises instance. To regenerate the token, run the command above and select Regenerate.
Once regenerated, the token must be updated on all workers in the instance, or they will stop to communicate: bash buddy update-worker-config --token TOKEN_VALUE

Configuration file

Storing configuration in a file is a convenient way to set up new and update existing workers 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

NameTypeDescription
drainBooleanDefines whether the worker is set to draining mode.
standalone-hostStringThe IP address of the main instance. Cannot be empty.
tokenStringThe authorization token generated by the installation wizard. Can be regenerated with buddy configure
worker-memoryNumberThe amount of RAM in MB allocated for the worker service.
tagStringThe tag applied to the worker. If set to empty (tag: ""), the tag is cleared.
cpusStringThe number of CPUs that can be used by the build actions on the worker. Can be equal to 0 (unlimited) or greater.
memoryNumberThe amount of RAM in MB that can be used by the build actions on the worker. Can be equal to 0 (unlimited) or greater.
concurrentStringThe number of concurrent pipeline runners on the worker. Can be equal to 0 (unlimited) or greater.
internal-hostThe IP address that will be bound by the worker. Default value: empty (binds to all IP's on the server).
external-hostThe external IP address of the server as seen by the primary server. Default value: the first detected external IP address.
runner-internal-portNumberThe listening port of the runner. Can be changed if the port is taken. Must be > 0 or will be ignored.
runner-external-portNumberThe 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-portNumberThe listening port of the registry. Can be changed if the port is taken. Must be > 0 or will be ignored.
registry-external-portNumberThe 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: "Worker-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 worker, shows the options listed below. To configure an option, type the corresponding number and press Enter.

  1. Worker data path – allows to move the application data on the worker to a different partition or disk
  2. IP & ports – allows to set IP & port addresses:

    • internal IP – the internal IP address to which the worker 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)
  3. Primary instance address – displays the IP address of the primary instance of Buddy.
  4. Worker token – displays the token used to authenticate in the primary instance of Buddy.
  5. Application memory management – changes the amount of RAM allocated to the Buddy application on the worker.

Checking worker status

You can view the list of connected workers and their status in the Workers tab of the On-Premises Admin panel:

Workers tabWorkers tab

Possible statuses:

🟢 Running 🟠 Draining 🔘 Drained 🔴 Not running or wrong version

Locking

You can lock a worker and change its name in the worker settings.

Locked workers cannot be assigned to new pipelines

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 workers. If any pipeline is currently assigned to the worker, you will find it at the bottom of the page:

Worker settingsWorker settings

Offline workers

If a worker 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 worker.

You can remove an inactive worker from the worker list. When you remove a worker, pipelines assigned to that worker will be automatically assigned to a different worker on the next execution.

Last modified on April 21, 2023

Get Started

Sign up for free and deploy your project in less than 10 minutes.