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.

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.

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. Approves the founder as a compute node and imports the answers document as the committed cluster intent.
  8. Starts the DNS server and requests the first certificate, when the answers document declares them.
  9. Performs the founder pivot.

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 credential​

Genesis writes the one-time root password to /root/triton-root-password with endpoint, username, and password lines. The global zone's /root does not survive a reboot, so this file is a handoff, not storage. Move it into your secret store and delete it. The password stays valid after the pivot, because the replacement tritond serves the same FoundationDB-backed user state.

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.

To sign in from another host, or if the automatic configuration reported a warning, run this on any host with tritonadm:

printf '%s' '<ROOT_PASSWORD>' | tritonadm configure \
  --endpoint http://<TRITOND_IP>:8080 --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.

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.

Next steps​