Cluster Configuration

In a cluster, several servers each do one part of the job: one runs the administration interface, one serves the user portal and Connect, one fronts telephony, and one or more process calls. Every one of them needs to know the same set of facts - which server holds the database, where each service listens, and what the other servers are called. Cluster Configuration is the screen that writes those facts down and sends them to every server.

Why you would want it

Without it, each server is configured on its own. Moving the database, adding a call-processing server, or renaming a host means editing files on four machines and remembering the same values four times. Anything you miss stays wrong until something fails, and the failure usually appears somewhere other than the machine that was missed.

This screen removes that work. You describe the cluster once, on the Servers screen, and the manager turns that description into the single file the rest of the cluster reads.

How it works

Three pieces are involved, and it helps to know what each one does.

The manager server builds a description of the cluster from the servers you have defined, and writes it to a file on its own disk (/etc/thirdlane/topology.yaml).
The configuration collector runs on the manager, notices that the file changed, and publishes it to a message bus that all the servers are connected to.
A configuration agent runs on every server. It reads the published description, writes out the settings its own machine needs, and restarts only the services that the change affects.

Nothing is copied over SSH and no server is logged into. The manager publishes; each server collects what applies to it. A server that is switched off during a change picks it up when it starts, because the description is held on the bus rather than pushed once and forgotten.

The screen only ever writes on the manager. Opening it on any other server is not possible, because the other servers are consumers of the description rather than authors of it.

Cluster shape

Two arrangements are supported, and the screen tells you which one you have.

Compact - the manager also serves the user portal and fronts telephony. Only call-processing servers are separate. This suits smaller clusters that need capacity rather than separation.
Expanded - user access and the telephony frontend each run on their own server. This is the arrangement to choose when administration, user traffic, and call traffic should not share a machine.

The names describe how the work is divided, not where the servers sit. Both shapes put call-processing workers on their own machines, and both are normally installed in one data centre; what differs is whether the manager carries user access and telephony as well.

The shape is set when the servers are first installed, not from this screen. It decides which server types the cluster can contain: a compact cluster is offered Manager and Telephony worker only, because it has no separate user or telephony servers by definition.

What can only exist once

A cluster has one manager, one User Access server, and one telephony frontend. Call-processing workers are unlimited. The Servers screen enforces this when you add a server, so the limit is reported when you try rather than discovered later in a file that will not work.

Standby servers are not counted against these limits, so a tier can be made redundant later without the limit getting in the way.

Using the screen

Define the cluster on the Servers screen: one row per machine, each with its full host name, its address, and what it does.
Open Platform > Infrastructure > Cluster Configuration. The summary at the top shows the cluster name, its shape, how many servers it has, and whether the file on disk still matches what the Servers screen says.
Read anything listed in the grid. It is empty when the description is sound. Warnings are worth understanding; errors stop the write, because a description that is wrong here is delivered to every server.
Select Preview to read the exact file that would be written. This is useful when comparing against a cluster that was set up by hand.
Select Write and Publish. The manager writes the file and asks the collector to publish it immediately.

Writing the description may restart services on the servers a change affects, so treat it as a maintenance action rather than a routine save.

Reading the results

Three outcomes are worth telling apart.

Written and published - every server has been told about the change and will apply it.
Written, publish pending - the file is correct on the manager but the collector was not triggered. The other servers pick the change up at the collector’s next check rather than immediately.
The collector is not installed - the file is written and goes nowhere. This appears as a warning in the summary before you write, and means the cluster software is not fully installed on the manager.

Best practices

Change the Servers screen, not the file. The description is rebuilt from those rows every time. An edit made directly to /etc/thirdlane/topology.yaml is replaced the next time you write from here. The previous version is kept alongside it as topology.yaml.prev if you need to compare.
Resolve warnings before they become errors. A server with a short name rather than a full one, or a service pointed at a host that is not in the cluster, will work until a certificate is checked or that service is called.
Preview before writing on a cluster set up by hand. If the cluster predates this screen, the preview tells you exactly what will change on every server.
Write during a maintenance window. Servers restart the services a change affects, and a topology change usually affects several.

Servers - defining the servers that make up the cluster.
Deployment Options - cluster architecture and when to scale out.
Data Sync - confirm each server applied configuration changes.