Skip to main content

Genesis on the founder

tritonadm setup bootstrap turns the founder into a working control plane in one run. It installs the signed zone images. It creates the founder FoundationDB and tritond zones. It installs the global-zone agent and creates the operator credentials. It approves the founder as a compute node and imports the answers document as the committed cluster intent. It starts the DNS server and requests the first certificate when the answers document declares them. Then it performs the founder pivot. When the run completes, the founder runs triton-fdb1, triton-tritond1, and tritonagent, and the CLI points at the new tritond.

An answers document whose admin network sets host_private: true describes a single-node datacenter. Genesis then runs no pivot. The founder zones triton-fdb0 and triton-tritond are the permanent control plane, and genesis prints founder pivot skipped: single-node datacenter (the founders are the survivors).

Before you start, confirm all of the following:

  • Every item under Requirements is true. Node zero is prepared, the networks reach their gateways, the parent zone delegates to the cluster, and the answers document validates.
  • tritonadm is installed on the founder. See Install the tritonadm CLI.
  • You are root in the founder's global zone.
  • You run under screen or tmux, or you redirect the output to a log file. Genesis takes tens of minutes. Most of that time is zone image downloads. The output contains the SSO root password in clear text, so a log file is a credential. See Save the root credentials.

Preview the plan​

Always run the dry run first. It changes nothing. It is the only step where you can read the whole plan before the control plane commits it. On the founder, as root:

tritonadm setup bootstrap --answers <ANSWERS_FILE> --channel edge --dry-run

The preview is what genesis will build. Read these sections in order:

SectionCheck
NODEThe founder matched the declaration you expect, and the section names the key that matched. machine shows the observed serial. Compare it with the declared serial.
NETWORKSThe address map for each network. The founder's own address is not inside a declared range.
CONTROL PLANEThe seat proposal and its failure domains. The genesis and target FoundationDB mechanisms.
EXTERNAL DNSThe exact parent-zone records to create. Create them now if you have not.
IMPACTWhat genesis preserves, creates, and destroys. Genesis adopts an existing zones pool and never rebuilds it.
FINDINGSEverything that validation flagged. Any error-severity finding stops the run.

The preview ends with two fingerprints. The answers words identify the document. The confirm words identify this plan against these facts. A changed plan changes the words.

To validate a document off-node, capture the founder's facts once. Then resolve the document against that snapshot with --facts <FACTS_FILE>. With --dry-run the run needs no addresses.

Run genesis​

danger

The founder pivot at the end of genesis deletes the founder tritond zone and decommissions triton-fdb0. A failed pivot fails the whole run and reports that genesis is not complete. To recover, correct the cause and run setup bootstrap again. The command refuses to run again after a completed pivot.

On the founder, as root:

tritonadm setup bootstrap --answers <ANSWERS_FILE> --channel edge --timeout 0

--timeout 0 removes the time limit on each API call. Image downloads and health gates are slow. A client timeout in the middle of a step is harder to diagnose than a long wait.

You can run genesis again after an interruption at any point before the pivot. After the pivot, the forward path is tritonadm setup converge.

Two flags let the run continue past a failed check. Both produce a degraded install instead of a working one. Prefer to correct the cause.

FlagEffect
--force-skip-dns-preflightContinue past a failed delegation check. DNS and certificates do not work until the delegation matches the plan. The reconciler enables them when it does.
--force-skip-cert-gateContinue when ACME did not issue a certificate inside the wait budget. The cluster starts without TLS until the certificate reconciler succeeds on its own.

--insecure-issuer accepts a plaintext single sign-on issuer for an answers document with no dns block. The issuer cannot change after a realm is seeded. Without a DNS name, the issuer is lost with the founder zone, and SSO cannot be recovered. Use this flag for labs that you will discard only.

What bootstrap does, in order​

  1. Resolves the answers document against the founder's facts and prints the plan.
  2. Fetches the channel manifest and verifies its minisign signature against the publisher key compiled into tritonadm, or reads --image-dir.
  3. Installs the triton-platform image and creates triton-fdb0. Then runs FoundationDB genesis.
  4. Creates triton-tritond, gated on http://<TRITOND_IP>:8080/v1/health.
  5. Installs tritonagent in the global zone and writes its endpoint to /opt/triton/tritonagent/etc/agent.env.
  6. Reads the one-time root password from the tritond zone and writes /root/triton-root-password at mode 0600. Then signs the CLI in with that password.
  7. When the answers document sets datacenter.dns.provider, stores the DNS provider API token. It reads TRITON_DNS_PROVIDER_API_KEY when that variable is set, and otherwise prompts for the token without echo.
  8. Approves the founder as a compute node and imports the answers document as the committed cluster intent.
  9. Starts the DNS server and requests the first certificate, when the answers document declares them.
  10. Writes the SSO root credential to /root/triton-sso-root-password.
  11. Performs the founder pivot, unless the datacenter is single-node.
  12. Records the channel it installed from as the cluster's channel.upstream_url, when that setting is unset. An --image-dir run records nothing.

The run ends with the credential and endpoint lines, the SSO lines, and:

== bootstrap complete — run `tritonadm setup converge` to continue ==

ClickHouse, object storage, and the booter are not part of bootstrap. They come from setup converge.

The founder pivot​

The founder starts as a cluster of one: triton-fdb0 and triton-tritond. Genesis builds a second pair, triton-fdb1 and triton-tritond1. It moves the FoundationDB coordinator to the second pair, retires the first pair, and points the CLI and the node agent at the second pair.

The pivot proves that the control plane can rearrange its own store before anything depends on it. A bootstrap that cannot do this must not hand over the system. For that reason a failed pivot fails the install instead of leaving a cluster that looks complete. If you see D6 founder pivot failed — genesis is NOT complete, see Troubleshooting an install.

Save the root credentials​

Genesis creates two root credentials and writes each to a handoff file at mode 0600, with endpoint, username, and password lines. The SSO file is written only when genesis can read the SSO password; if the write fails, genesis prints WARNING: could not preserve the sso root credential and continues:

FileCredential
/root/triton-root-passwordThe tritond root user
/root/triton-sso-root-passwordThe SSO directory (identityd) root user

The global zone's /root does not survive a reboot, so these files are a handoff, not storage. Move both into your secret store and delete them. The passwords stay valid after the pivot, because the replacement zones serve the same FoundationDB-backed state.

danger

Genesis also prints the SSO root password to standard output, on the line that starts with sso root pw. If you redirected the output to a log file, that file holds the password in clear text. Move the log into your secret store or delete it, together with any copy in screen or tmux scrollback.

If genesis cannot recover the SSO password, it prints sso root pw not recoverable from logs followed by the command that resets it. If the SSO directory is not running at all, it prints sso NOT RUNNING and password sign-in to tritond still works.

Sign in​

Genesis points the CLI at the post-pivot tritond. If the founder's global zone cannot yet resolve the cluster's own DNS names, genesis uses a plaintext host-local address instead and reports that. This is expected before the delegation works.

If the automatic configuration reported a warning, sign in on the founder. This address is plaintext, so use it only from the founder. On the founder, in the global zone, as root:

printf '%s' '<ROOT_PASSWORD>' | tritonadm configure \
  --endpoint http://<TRITOND_IP>:8080 --username root --password-stdin

To sign in from another host, wait until the cluster has its certificates, then use the HTTPS endpoint. On that host:

printf '%s' '<ROOT_PASSWORD>' | tritonadm configure \
  --endpoint https://tritond.<DC_DOMAIN>:8443 --username root --password-stdin

Then create a long-lived key and stop using the stored root token:

tritonadm api-key create --description "operator key"

Check that the control plane answers​

On the founder, as root:

tritonadm whoami
tritonadm fdb status
tritonadm cn list
tritonadm intent show

fdb status reports redundancy, coordinators, and fault tolerance. cn list shows the founder as an approved compute node. intent show prints the fingerprint words of the committed answers document. They match the preview.

tritonadm fdb status reaches FoundationDB through tritond. When tritond is unreachable, add --break-glass to read the FoundationDB zone directly over zlogin from the global zone. --zone selects the zone alias and defaults to triton-fdb0, which the pivot destroys. After the pivot, on the founder, as root:

tritonadm fdb status --break-glass --zone triton-fdb1

Start over​

tritonadm setup destroy removes what setup created on this host. By default it prints the plan and prompts for confirmation. --yes skips the prompt. It does not destroy the zones pool, because setup adopted that pool and did not create it.

danger

setup destroy deletes every control-plane zone on this host, with its data, and then the images those zones used. That covers triton-fdb0, triton-tritond, triton-mantad0, triton-booter0, triton-clickhouse, triton-dnsedge0, and the numbered triton-fdbN, triton-tritondN, and triton-mantadN zones. There is no undo. It acts on this host only, so seats on other compute nodes keep running. It leaves /root/triton-root-password, /root/triton-sso-root-password, and the tritonadm configuration in place.

On the founder, in the global zone, as root:

tritonadm setup destroy

Next steps​