configure

Configuring Overlord

Overlord ships with safe defaults that work for most installations, however, some parameters may or may not be suitable for all use cases, so it is worth spending a little time configuring them.

Note that after changing a parameter you must restart the Overlord processes using supervisorctl restart overlord:. The overlord-watch-commands process is not included in the overlord process group so you must restart it individually. The reason for not including the overlord-watch-commands process in the overlord process group is that it is designed to be minimally configured so it should be rare when it needs to be restarted and should not be restarted unless strictly necessary as doing so may cancel currently running jobs.

For more details, read the man pages.

Current Configuration

Overlord uses a default configuration when one is not specified and can be viewed using the print-config command:

# OVERLORD_CONFIG=/usr/local/etc/overlord.yml overlord print-config
{
    "serverid": "/opt/pipx/venvs/overlord/overlord/serverid",
    "port": 8888,
    "debug": false,
    "compress_response": true,
    "polling": {
        "jail_stats": 12,
        "jail_info": 8,
        "projects": 6,
        "jails": 4,
...

Number of jobs

The default number of jobs (max_watch_commands) is the number of available CPUs and this parameter is essential for the overlord-watch-commands process. It represents the maximum number of processes spawned by this command, processes in charge of creating projects and VMs.

API labels

A client will need the API labels to see if they match the desirable labels in their deployment file, so you must set them up before using Overlord.

labels:
  - all
  - db-only

Although you can use any labels you want, at least put all as a label, so if users want to deploy to all machines they can use that label as a convention.

Skew

Overlord reads from disk directly, or indirectly using AppJail commands. In most cases the former is enough and the most efficient way to get the information available from the jails, but the latter is used to get more complex information such as that used by appjail-jail(1) which is a bit slower. Overlord processes perform the above operation in a loop or, in other words, through a polling mechanism so it may be worthwhile to configure the interval used.

polling:
  skew: [6, 10]

The skew represents a range of numbers (min, max) and is used to calculate a random number that is added to each interval of each command, so it is not so deterministic. A not so high number is recommended to keep the information up-to-date as fast as possible.

Heartbeat

A useful feature of Overlord is "Smart Timeouts" (also known as Circuit Breakers), but they are not proactive. Heartbeats are a complement to "Smart Timeouts" to detect when a chain is unavailable by "pinging" it. They are not enabled by default, as you may not want to have a process making HTTP requests at random intervals, however they are easy to configure.

polling:
  heartbeat: 10

The overlord-poll-heartbeat process is in charge of performing the described operation, but when the previous parameter is not configured it exits without doing anything, so it is necessary to start it.

supervisorctl start overlord:overlord-poll-heartbeat