The cluster passport
Status. The report builder, the three formats (golden files), the secret scrubbing and the read-only page's request handling are unit-tested. Not run against a large or live fleet; the machine list comes from
GET /fleet/nodesas documented.
One document you can give to someone else (a colleague, a landlord, yourself in a year) that says what this cluster is and how to look after it.
fluxctl cluster report # Markdown on the screen
fluxctl cluster report --format html --out passport.html
fluxctl cluster report --format json # for scripts
fluxctl cluster report --serve # a read-only page at http://127.0.0.1:7801/
Run it on the server (it reads the operator token the same way cluster pending does) or pass --server and --token-file. If the server cannot be
asked, the report is still produced, with a note saying so.
What is in it
- Summary: machines, how many are online, offline, cordoned or outdated, machines asking to join.
- Machines and roles: name, role (Mac or Linux), CPUs, memory, VMs, agent version, status, last seen.
- Versions: fluxctl and each node agent version, with a warning when they differ.
- How to add a machine:
fluxctl cluster pair, the approve step, the--serverfallback, and whether pairing is on (cluster-pairing.md). - How to back up and restore the server's state directory.
- How to undo: cordon, deregister, stop pairing, roll back a version, uninstall a recipe app.
- Where the logs are on a Mac, on Linux and on the server.
- Apps installed from recipes (recipes.md).
- Contacts and notes: the contents of
~/.config/fluxvm/passport-notes.md(or--notes-file FILE). Who to call, where the spare mini is.
Secrets are never in it
Two layers. The report is built from a fixed structure that has no field for a token, credential, password or key (a test checks the field names).
Then everything written, in every format, passes a scrubber that replaces anything shaped like a secret: fvnc_/fvjt_ credentials, GitHub, Slack
and AWS style tokens, JWTs, long hex strings, password=/token:/Bearer ... values and user:password@ in URLs. A test pastes a dozen such values into the notes,
a machine name, the server address and a note and checks that none appears in Markdown, HTML or JSON. The scrubber errs toward removing too much:
a very long random-looking word in your notes may be replaced by [redacted]. It is a safety net, not permission to paste secrets into the notes file.
The backup advice names the files in the state directory but never reads them; note that the archive itself contains the enrollment secret and must be kept private.
--serve
Serves the same report on 127.0.0.1 only, read-only: GET only, the Host header must be 127.0.0.1:PORT or localhost:PORT (so a web page elsewhere cannot read it
through DNS rebinding), strict CSP, no cache, / (HTML), /report.md and /report.json. Each request looks at the cluster again.
There is no authentication because it listens on loopback; do not forward the port.