Step 1. Choose a topology

A topology says which services to install, and which server each service runs on. You make a topology once. Then you can use it for many customers. This page shows how to choose a topology or build a new one.

For the words used here, see Words you need to know. For the whole install, see Install the system at a customer site.

What a topology is

This section explains a topology with an example.

A topology is a list of two things:

the services to install, for example ftacs, mysql and ui-backend;
the server each service runs on, for example "server 1" and "server 2".

A topology is a template. It is not one customer’s install. It holds no server addresses, no passwords and no values. Those belong to the installation. You create the installation in Step 2. Create an installation. Several installations can use the same topology.

Every topology records who designed it and who changed it last. Some topologies were saved before the tool recorded this. For them, both lines are empty. The tool does not guess a name.

Before you start

This section lists what you need before you choose or build a topology.

To create or edit a topology, you need the user role. You also need to start training module T4, Build a topology. This is separate from being an admin of this application.
Know which parts of the product the customer bought, for example API, Portals or Monitoring.
Know how many servers the customer gives you.

Steps: use a topology that already exists

This section shows how to find a topology that fits the customer.

Open the Topologies tab.
Type a word in Search to filter the list by name or description.
Use ▦ Graphical to see each server and its services. Use ☰ List to see a compact table.
Find a topology with the right services and the right number of servers.
Remember its name. You pick it in Step 2. Create an installation.

If no topology fits, build a new one. See the next section.

Steps: build a new topology

This section shows how to build a new topology. The builder has three steps: What runs, Where it runs and Name and save.

Open the Topologies tab.
Click + Build topology.
On What runs, look at the core services. They are always on. Every install needs them.
Under Presets, click the groups the customer needs, for example API, Portals or Monitoring.
To add one more service, type its name in Filter services… and tick it.
Click Next.
On Where it runs, set the number of servers in Hosts. Use − and +.
Click Auto-balance to let the tool place the services. Or tick the boxes yourself: one box for each service and server.
Check the messages under the board. Fix every row that the tool marks.
Click Next.
On Name and save, type a Topology name, for example custom-2host-mysql.
Click Save topology.

To go back one step, click Back. To remove all ticks on What runs, click Clear selection. To remove all placements on Where it runs, click Clear placement.

To change a topology later, click Edit (or ✎ Edit) on its card. The builder opens with every step already filled in. The save button then reads Update topology.

What you see

This section describes the builder screen.

A rail at the top shows the three steps. It counts the open problems in each step.
A step after the last step you reached stays closed. You save on the last step.
When you edit a topology, every step is already reached.
On Name and save, a preview shows the topology definition before you save.

Services, roles and instances

This section explains three words. Each word answers a different question.

Word What it means

Word	What it means
Service	One thing that runs: a container, one row in the service catalogue. For example `ftacs`, `mysql`, `ui-backend`.
Role	A name for a group of servers. The topology author gives this name. With roles, a topology can place services without naming real servers. The tool stores a load balancer’s address for each role.
Instance	One server. In a topology, it is a numbered slot, not a real machine. An installation connects each slot to a real hostname. If this tool reaches the server, the slot also gets an SSH credential.

Service

One thing that runs: a container, one row in the service catalogue. For example ftacs, mysql, ui-backend.

Role

A name for a group of servers. The topology author gives this name. With roles, a topology can place services without naming real servers. The tool stores a load balancer’s address for each role.

Instance

One server. In a topology, it is a numbered slot, not a real machine. An installation connects each slot to a real hostname. If this tool reaches the server, the slot also gets an SSH credential.

A service can run on more than one server. Then it has one copy (a replica) on each of those servers. You cannot put two replicas of one service on the same server. The tool refuses this with a message.

The list of services: core, presets and dependencies

This section explains how the list of services is built.

Every topology starts with the core services. The core is always on.
You add presets. A preset is a group of services, for example API, Portals, AI, QoE, Monitoring or Testing.
Some services need another service to work. This is a dependency. When you tick a service, the tool adds its dependencies for you.

The tool adds only the mandatory dependencies. It never ticks an optional dependency for you. Because of this, a topology that looks complete in the builder does not fail later because of a missing dependency.

Services that must run on the same server

This section explains services that you cannot put on different servers.

A service contract can say that two services must run together. The contract uses same_host_as for this. A pair like this does not work across servers, for one of two reasons:

The two services call each other on localhost.
Or one of the two services publishes no port that other servers can reach.

So every server that runs one of the pair must also run the other one. This also applies when one service runs on more servers than its partner. The tool checks this when you save. It refuses a topology that breaks the rule.

The tool also tries to keep services that often run together on the same server. This is only a preference. The tool refuses only a pair that a contract declares with same_host_as.

Placement: which service goes on which server

This section explains the Where it runs step.

Placement is a table. It has one row for each replica and one column for each server. You tick one box in each row. A replica runs on exactly one server.

Each row shows what the service needs, and where that runs:

If the needed service is on the same server, the row names it.
If it is on another server, the row shows an arrow and the name of that server.

A diagram shows the calls between servers. It draws one line for each pair of servers that call each other. Calls inside one server show as a number, not a line. Point at a service on the diagram. It then highlights what that service needs, and what needs that service.

The name of a host group is important. The tool stores the customer’s load-balancer addresses under this name (see The load balancer). The wizard names the group after the host alias you type. So when you rename a host, you change more than a label.

Auto-balance places the services for you. It puts services with more dependencies on servers with higher numbers. The result always has a valid start order.

Sometimes auto-placement cannot load the dependency data, for example when a request fails. Then it uses a simpler arrangement. It says so on screen, in two places. The message stays visible.
It may raise the number of servers you asked for. It tells you when it does this.
If it cannot meet a requirement, it names that requirement.

The maximum is twelve servers.

The tool refuses placement, and does not only warn, when:

A replica has no server yet.
Two replicas of one service are on the same server.
A same_host_as pair is on different servers.
Two services on one server publish the same host port.

Each refusal names the replicas and servers with the problem. It has a link to the row that you need to fix.

Deploy waves: two servers that need each other

This section explains what happens when two servers need each other.

Example: server 1 runs ftacs and provision-api. Server 2 runs northbound-api. Server 1 calls server 2, and server 2 needs server 1. The tool can deploy this. It deploys in waves.

A wave is one visit to one server.
The tool visits a server more than once only when another server must start in between.
A simple topology deploys each server in one visit.

The tool works out the waves from the topology. You do not set them. You see the waves on the deploy panel and in deploy.sh. See Step 6. Deploy for what you see while a deploy with several waves runs.

Database replica

This section explains how to add a copy of the database.

Place mysql on two servers instead of one. The topology then has a primary database and a replica. They are not two separate databases. The server with the lower number gets the primary. The other server gets the replica. The order you place them in does not matter. To make another server the primary, put mysql on the lower-numbered server.

The tool then does these things for you:

It creates a primary configuration and a replica configuration, one on each server.
It creates a replication account. On the first start, the replica connects to the primary and copies its data.
It points the database connection of every service to the primary.

The tool does not do two things:

It does not set the stricter read-only mode. That mode would stop a failover tool from making the replica the new primary.
It does not copy data that the primary already has. If the primary already holds data, someone must copy it once by hand, before replication starts.

The load balancer

This section explains how the tool uses the customer’s load balancer.

A load balancer is the customer’s own device in front of a group of servers. This tool does not create or manage it. It only records the address of the load balancer. Then the tool gives the customer the load balancer’s address, not the address of one server.

You enter it on the installation, not on the topology. Many customers share one topology. So you enter the load balancer address on each installation, one for each host group.

Renaming a host group disconnects its load balancer. The tool stores the address under the group’s name. After a rename, the tool finds no address. The addresses change back to the address of each server. The public row disappears. A customer can then get one server’s address and think it is the load balancer. The tool shows this on the installation. It does not block anything. Set the load balancer again under the new name.

Only people and outside clients use the load balancer. Services do not talk to each other through it:

Service-to-service addresses: the load balancer may not be reachable from inside the customer’s network. Each service also talks to its own partner on purpose.
Cluster and peer addresses: each member needs its own address. Otherwise the cluster cannot form.
Database addresses: a write must reach the primary.
The deploy itself: the tool installs the bundle on each server separately.

To make one service use the load balancer, change that one value on that installation. A value you type always wins over a value the tool computes.

The panel shows two kinds of address row. The first row is the load balancer’s own address. This is the address you give to the customer. Below it, the panel shows every server’s own row. Each row is checked separately. So one dead server behind a healthy load balancer does not look green. See entry points.

One limit: the tool assumes the load balancer uses the same ports and scheme as the servers behind it. The tool does not handle a load balancer that ends TLS itself or changes a port.

Good to know

This section lists rules about saving, renaming and changing a topology.

What the tool refuses to save

This section lists why the tool refuses to save a topology. The tool refuses, and does not only warn, in these cases:

A replica has no server.
Two replicas of one service are on one server.
A same_host_as pair is on different servers (a same-host violation).
Two services on one server publish the same host port (a port-collision violation).
Two hosts have the same name.
Replicas of a peer cluster are on one server. That is not a real cluster.
The topology name or the server count has a problem. The name can use lower-case letters, digits and hyphens. It cannot start or end with a hyphen.
A service is scheduled here and also marked as supplied by the customer. Pick one.

When a placement rule stops the save, the message starts with Nothing was saved. Some refusals are shown as Save failed instead, for example a bad name or two hosts with the same name. Nothing was saved in that case either.

Two refusals tell you where to go:

A same-host violation says on which server each of the two services is placed.
A port collision names the port, the server and both services.

The tool never disables Next or Save without a reason. Press the blocked button to see why. The tool states the reason, opens the step with the problem and marks the rows that cause it.

Renaming and deleting a topology

This section explains how to rename and delete a topology.

You cannot rename a topology. While you edit it, the name box says: "Pinned while editing — delete and recreate to rename."
To change the name, build the topology again with the new name. Then delete the old one.
To delete a topology, you need the support_admin role. Click the bin icon on its card, or Delete in the List view. Then confirm with Delete and the topology name.
You cannot delete a topology that installations still use. The refusal names this as the reason.

So you cannot rename a topology that is in use at all. Choose the name carefully. Every installation refers to the topology by this name.

What a change to a topology does to installations

This section explains what happens to installations when you change their topology.

You can change a topology after installations use it. For example, you add or remove a service, or move a service to another server. An installation that is missing an answer for the change is called behind. The missing answer is usually a variable or an image tag.

When you save the change, the tool names the installations that are behind:

For one installation, it shows a direct link to fill in what changed.
For more than one, each installation gets its own row and its own count of missing items.

An installation that is behind blocks Deploy and Download until you fill in the missing answers under Variables. See why an action is muted.

A service that you removed from the topology keeps its stored values on the installation. The tool does not delete them. You remove them yourself on the Variables screen.

A change that affects no installation shows no message at all.

If something goes wrong

This section covers refusals that you cannot fix on the board.

The topology cannot start at all

This section explains the one kind of loop that the tool cannot deploy.

Two servers that wait for each other are fine. Deploy waves handle that. But a loop between services cannot start. In such a loop, each service waits for the next one. No placement on any number of servers can start them.

This refusal says:

these services wait for each other;
moving one of them to another server will not help;
what each service waits for must change.

It asks you to send the topology’s name to the platform team. It is an escalation, not a task. Nothing on the board can fix it. The refusal names only the servers that are part of the loop.

Two more facts:

You cannot edit a topology with such a loop at all until the loop is gone. This includes a change to the description only.
On an instance where service contracts have never been synced, both checks at save are off. Every topology saves. The refusals appear after the contracts are synced. Then open again every topology that was saved before.

For other problems, see When something goes wrong.