Set public names and preview domains

This guide keeps the public edge of a cloud in its supported shape, keeps the tritond front door off, sets the Cloud API names, and keeps sandbox previews off.

The public edge is triton-adc. It is the load balancer in the gateway zone image, and it is built on Pingora. Customers reach the Cloud API, the portal, and sign-in through triton-adc. It sends each public name to its backend. With the tritond front door off, identityd keeps its TLS listener on port 443 in the tritond zone, behind triton-adc.

tritond also has a TLS listener of its own, called the front door. Its switch is the zone metadata key triton:front_door. Triton Cloud does not use the front door. Keep it off. Genesis turns it on for a standard install, so check each tritond zone.

Sandbox previews are not enabled. Tenants reach sandbox ports with tritonctl sandbox port-forward, which goes through the Cloud API and needs no preview names. Preview hosting will move into triton-adc in a later release.

Keep the front door off

triton:front_door is on or off, and the default is off. Set it as zone metadata. The tritond and identityd start methods both read the key, so exactly one of the two binds port 443.

`triton:front_door`	`tritond`	`identityd`
`on`	Binds the front door, on `0.0.0.0:443` unless `triton:tritond_front_door_bind_address` names another address.	Binds no TLS listener, and trusts `127.0.0.1/32` for `X-Forwarded-For`.
`off`	Binds no front door. It checks the front door keys but does not use them, and logs one warning.	Binds `triton:identityd_tls_bind_address`, which defaults to `0.0.0.0:443`. It refuses `none` and does not start.

A bind address alone does not turn the front door on. With the switch off, previews are off on that node.

Genesis writes triton:front_door=on when the identityd issuer is a DNS name whose host differs from the console's host. A genesis whose dns block enables ACME, which is the standard install, names the issuer auth.<DOMAIN> and the console <DOMAIN>, so it turns the front door on. It also sets triton:tritond_api_names to the console's host and forwards the issuer name to identityd on 127.0.0.1:8090.

Zones built before the triton:front_door key existed have triton:identityd_tls_bind_address=none and no triton:front_door key.

Check a zone's front door keys

This check reads the keys and changes nothing. Run it in the global zone of the compute node that hosts the tritond zone, as root. Find the zone's UUID first; it is the zone whose alias starts with triton-tritond:

vmadm list -o uuid,alias

Then read the two keys:

zlogin <TRITOND_ZONE_UUID> mdata-get triton:front_door
zlogin <TRITOND_ZONE_UUID> mdata-get triton:identityd_tls_bind_address

mdata-get fails for a key the zone does not have. The start methods treat a missing triton:front_door as off.

Turning the front door off on a running zone

Turning the front door off on a running zone moves port 443 from tritond to identityd. No verified procedure for that handoff exists yet. Do not change the front door keys on a running zone until the procedure is documented.

Set the API names

The API names are the cluster setting api.names. Set them to the names that triton-adc sends to the Cloud API. On an operator workstation with a configured tritonadm:

tritonadm config set api.names <API_NAME>[,<API_NAME>...]

Every tritond has the new names within 5 seconds, with no restart. With the front door off, tritond checks the names but does not serve on them. With it on, the front door serves the Cloud API on a name only once the zone bundle's certificate in /data/tls names it. Until then, the TLS handshake for that name fails and tritond logs a warning that names it. The checks keep a later preview domain off the API's registrable domain. tritond refuses an empty list, a name listed twice, a forwarded service's name, and a name that shares a registrable domain with a preview domain.

An upgraded cloud imports triton:tritond_api_names into api.names once, when the setting is unset. After that, tritond logs a warning about the metadata key at each start. Leave the key in place: it holds the zone's boot names, which tritond falls back to when api.names is reset.

tritonadm config reset api.names makes the setting unset again, and tritond then uses the zone's boot names. With the front door on and no boot names, the reset is refused with is unset and the zone gives no API names; the front door needs at least one.

Keep previews off

Previews are off until you list a preview domain, and the default is none. Leave preview.domains unset. With no domain:

The Cloud API returns no preview URL for a sandbox.
tritonctl sandbox ports open, the preview token, and tritonctl sandbox url stop with the message below. For ports open and the preview token, the API answers 403 FeatureDisabled. tritonctl sandbox ports close is not refused.
The capability document lists ports and preview_urls as refused.
preview_public has no effect.

The message:

previews are not enabled on this cloud; use port-forward (the `preview` sandbox feature is off)

After a 403, tritonctl adds this hint line:

`tritonctl sandbox port-forward <sandbox> <port>` reaches the port from this machine instead

Port tunnels, RDP tunnels, code runs, exec, and files do not need previews.

Check the state:

tritonadm config features

The preview.domains row shows off.

Do not set a preview domain yet. With the front door off, nothing serves the preview names, so a preview URL would not answer.

Turn previews off after they were on

tritonadm config set preview.domains ""

tritond stops issuing preview URLs at once and retires the preview DNS zones, so their certificates are not renewed. The front door stops serving the preview names at once, and open preview WebSockets close. To keep the domains and turn previews off for tenants only:

tritonadm config set sandbox.feature.preview off

An upgraded cloud that had triton:tritond_preview_domains keeps its domains: the first start imports them into preview.domains. Set preview.domains to "" to turn previews off. An empty preview.domains is a setting, not unset, so tritond does not import the metadata again. tritonadm config reset preview.domains also stores an empty list, so previews turn off and the metadata is not imported again.

Each tritond checks the stored names against its own boot settings. If they stop passing on a node, for example after a boot setting changed there, previews turn off on that node and tritond logs why. The API names that still pass stay served, and the preview DNS zones are kept. Fix the setting and previews come back. The node that takes a config set reloads the names at once. The others read them again within 5 seconds.

Keep the front door off​

Check a zone's front door keys​

Turning the front door off on a running zone​

Set the API names​

Keep previews off​

Turn previews off after they were on​

See also​