Managing several servers
One console can manage several Antelao servers. Each registered server is an environment, and the console switches between them the way a Docker management UI switches between endpoints.
This is the chapter for hosting companies. If you run one server, you already have exactly one environment, the built-in local one, and nothing here applies.
Quotas
| Environments | Unregistered | Community | Developer | Professional | Provider |
|---|---|---|---|---|---|
| Limit | 1 | 1 | 1 | 3 | Unlimited |
The count includes the built-in local environment, so each limit allows one registered server fewer than the number shown.
Registering one above the limit is refused. When the license stops carrying this feature, every registered environment is disabled: the console stops connecting to it, and its registration and key are kept. A license with a lower limit disables the newest ones above it. Either way they are managed again by themselves when a license allows it. See When the license changes.
Registering
Environments in the console. Each environment needs the target server's management API URL
(https://<server>:5312) and an API key for it, issued on that server (Keys and credentials).
The target server has to let this console in first. A fresh install closes its management API to
the outside: it answers the server itself and the private ranges 10.0.0.0/8 and 192.168.0.0/16
only. Unless this console reaches it from one of those, add this console's address on the target
server under Security > Firewall (the Rules tab, api), or with apiAllow when you install
it; First, let your address in lists
every way.
Groups and Tags beneath it organise a long list: a group gathers servers that belong together, and tags cut across groups.
Issue the key on the target server, on Security > API keys with Issue a key for a console that manages this server (surface Management API), and enter it in the API key field here. With that key the target server acts only for a person of this console who has an enabled account there with the same user name. It gives them the lower of the role this console names and the role of that account, on the instances both allow, and the surfaces, level and instances chosen for the key limit it further. A person with no enabled account there is refused, and the refusal is recorded in that server's Security > Audit.
Any other key is refused for every signed-in person, Administrators included: an ordinary key from
Issue a key, a key that ohm connection add stores for that server, and the console key that
ohm server info --show-secrets shows there, which acts only for a person signed in to that server's
own console.
After updating to 0.24.0: re-key every environment
A key entered under Environments before 0.24.0 was an ordinary key, and from 0.24.0 on it is refused. Once both servers are updated, for each registered environment:
- On that server, open Security > API keys and press Issue a key for a console that manages this server. Copy the key; it is shown once.
- On this console, open Environments, edit that environment, choose Replace the key under API key, and enter the new key.
- Revoke the old key on that server's Security > API keys.
Until then nobody signed in here can work on that environment. A registered server that is not yet on 0.24.0 does not apply a person's role, so this console refuses its answers to Viewers, Operators and Read-only administrators until it is updated and re-keyed.
After updating to 0.25.0: create the accounts there
From 0.25.0 on, a registered server acts only for people who have an account of their own on it. Before updating it, for each person of this console who works on that environment:
- On that server, open Security > Users and create an account with the same user name as on this console.
- Give it the role and the instances the person needs there. This console cannot give them more.
The key decides how far a person can go too. A read-only key keeps them read-only, a key limited to some instances keeps them to those, and only a read-write key for every instance lets anyone work there as an Administrator.
The Instances list covers the fleet
With more than one environment registered, Instances lists every connected environment's instances in one table rather than making you switch servers to see them. An instance that lives on another server is marked with a muted globe.
An instance's own page names the server it lives on, and an account can star a default environment.
When a registered server's certificate changes
When a registered server presents a certificate that no longer matches the one pinned when you registered it, the connection is refused, and the refusal is not the end of it: the console shows you the new fingerprint and lets you trust it deliberately.
That matters because the alternative behaviours are both bad. Trusting silently would make pinning pointless; refusing with no way forward would mean a reissued certificate takes an environment out of your console until somebody re-registers it from a shell.
Compare the fingerprint against the server itself before accepting it. A changed certificate is usually a renewal, and occasionally is not.
Moving an instance to this server
Move an instance here, on the Instances page, takes an instance of another of your servers, stops it there, carries it over and restores it here as the same instance, with the same configuration and the same databases.
It is a move, not a copy: the instance stops on the server it came from. Plan it as an outage of that instance for as long as the carry takes, and expect the archive to travel at the speed of the slower of the two servers' disks.
User scoping across environments
Users are scoped per environment as well as per instance. A customer's operator can be given access to their instances on one environment and nothing at all on another. A Viewer or Operator assigned to a registered environment sees only the instances assigned to them there, and everybody accepts that server's license agreement once, on their first visit.
Each registered server holds a person to the role and instances this console names for them, and never beyond the account they have there: a Viewer, Operator or Read-only administrator is refused there what their role does not allow, such as the downloads that carry credentials, the live two-factor codes and every change outside their role. A person with no enabled account there is refused everything.
The browser editor opened on a registered server from this console carries none of the git credentials or SSH keys of the person's account there, and starts apart from the editor that account opens when it signs in there. Push from it after signing in on that server itself, or from your own machine.
Who a person is, and which role and instances they have, is decided by the console, not by the servers it manages. A managed server's authorisation layer has no concept of environments at all.
What each registered server sees is a caller holding the key issued for this console, together with a user name, role and instances that the console asserts in request headers. The server checks that user name against its own accounts and never gives more than that account holds, but it cannot tell whether the person behind the console really is that account's owner. For who is at the other end, it believes the console.
Three consequences worth planning around:
- Registering an environment hands the console lasting access to that server, as far as the key's surfaces, level and instances reach. Revoking it means revoking that key on the server's Security > API keys, not deleting a row.
- The console is a single point of compromise across every registered server. Whoever controls it controls all of them, whatever the per-user scoping says.
- Per-environment scoping is exactly as strong as the console's own correctness. It is a usability and least-privilege control, and a good one. It is not an isolation boundary between customers.
If two customers must be cryptographically separated rather than administratively separated, give them separate consoles.
What runs where
Each environment is a full Antelao server with its own API, job queue, scheduler, license and master database. The console is a client of all of them.
Consequences worth internalising:
- Licenses are per server. Registering an environment does not extend your license to it. Each server needs its own, and each enforces its own quotas.
- Jobs run on the server they belong to. There is no cross-server queue.
- An unreachable environment is unreachable, not broken. The console reports it and carries on with the others.
The local environment is always there
It cannot be removed and does not count against a registration. A console with no license still manages its own server.