Services

A service is an internal app with its own name and address, separate from any one machine. You run it on one or more machines (its hosts), and every device reaches it by the service's name. If the host in use goes offline, devices move to the next one.

Use it for anything people rely on every day: a wiki, Grafana, an admin tool, a Git server. Services work over TCP.

Set one up

1. Create the service. In the dashboard, open Services and add one with a name (like grafana) and its ports (like tcp:443). It gets an address from 100.100.0.0/16 and a name.

2. Run it on each host. On every machine that runs the app, tell the client which local port to send the service's traffic to:

   bash

   underpass serve --service=svc:grafana --tcp=443 127.0.0.1:3000

   The target can be a port (3000), 127.0.0.1:3000 or localhost:3000.

3. Approve the hosts. In Services, approve each machine. A machine only serves once an admin approves it.

People then open https://grafana (or the service's full name) from any device in the network.

Which host is used

Every device picks the same host, so everyone sees the same app state:

1. Hosts that are approved and currently serving are candidates.
2. Online hosts come first, then the one that has served the longest.
3. Each device uses the first candidate it can reach.

This is failover, not load balancing: one host serves at a time, and the others wait as backups.

Failover timing

For planned maintenance, stop serving first:

underpass serve --service=svc:grafana --tcp=443 off

Then update or restart the machine, and run the serve command again.

See what a machine serves

underpass serve status

Limits

• 1 to 16 ports per service, TCP only
• Up to 64 services per host
• Service and machine names share one namespace: a service can't have the same name as a machine

Access

Only devices in your network can reach a service. To narrow it further, name it in an access rule as svc:grafana.