Stacks on #53 (cluster doctor) — merge that first; this branch is based on feat/cluster-doctor, so the diff here is just the join half.
This is #2 of the 27.1 tooling roadmap: guided cluster membership. doctor (#53) was the read-only reachability preflight; this is the node-side configuration that follows it.
Topology v2
A server machine may now carry an optional cluster block. It names where this node reaches the shared SQL store, the coordinator and the blob store, what role it takes, and what units it must start after. Every address in it is the operator's — the installer bakes in none of its own, and a file with no cluster block is read exactly as a v1 file was. Load accepts versions 1 and 2; a cluster block requires version 2.
Validation relaxes the old "one mail server only" refusal: multiple servers are allowed iff every mail node carries a cluster block (a clustered install); a mix is still refused.
inbuxa cluster join -f FILE
Acts on this machine's block only — it never reaches another node; the file is copied across and run on each, like the rest of the installer.
Install the secrets every node reads from disk (store / coordinator / blob), each 0400, owned by the server user. A secret with secret_from is installed from it; one without must already be in place.
Keep the current config.json aside once as config.json.prev (rollback), then point the server at the shared store.
Write the cluster.conf drop-in (INBUXA_HOSTNAME, and INBUXA_ROLE unless this is the node that carries every task) and, when after is set, cluster-order.conf (After=/Wants=).
daemon-reload and restart.
--dry-run prints every file it would write, with contents, and stops. The real run needs --yes and root.
Scope — node half only (by design)
This configures a node joining an already-initialised cluster. A joining node reads the blob store and coordinator definitions from the shared store the moment its config points there; all it needs locally is the store config and the File secrets those definitions reference — which is exactly what this writes. Seeding the shared registry (the x:BlobStore / x:Coordinator / x:ClusterRole objects) is the one-time cluster-creation step, not something each node repeats, and it carries tuning that doesn't belong hard-coded in a general installer; it's left out here deliberately. The schema still names the coordinator/blob endpoints so the file is complete and their secrets land beside the store's.
Tests & checks
New: internal/cluster/join_test.go (plan build, config.json shape, secret install + modes, drop-in contents, rollback copy, dry-run writes nothing, missing/preexisting secret), internal/topology/cluster_test.go (v1 still valid, cluster needs v2, must run a server, clustered multi-server, field validation). Full go test ./..., go vet (amd64 + arm64), gofmt, and the stdlib-only check all pass locally. No new dependencies — stdlib only.
Not merged; opening for review.
Stacks on #53 (`cluster doctor`) — merge that first; this branch is based on `feat/cluster-doctor`, so the diff here is just the join half.
This is #2 of the 27.1 tooling roadmap: guided cluster membership. `doctor` (#53) was the read-only reachability preflight; this is the node-side configuration that follows it.
## Topology v2
A server machine may now carry an optional `cluster` block. It names where this node reaches the shared SQL **store**, the **coordinator** and the **blob store**, what **role** it takes, and what units it must start **after**. Every address in it is the operator's — the installer bakes in none of its own, and a file with no cluster block is read exactly as a v1 file was. `Load` accepts versions 1 and 2; a cluster block requires version 2.
```json
"cluster": {
"store": {"type": "PostgreSql", "host": "HOST", "port": 5000, "database": "inbuxa",
"user": "inbuxa", "secret_file": "pg.pw", "secret_from": "/path/pg.pw"},
"coordinator": {"addr": "HOST:4223", "secret_file": "nats.pw", "secret_from": "/path/nats.pw"},
"blob_store": {"endpoint": "http://HOST:3910", "bucket": "blobs",
"secret_file": "s3.secret", "secret_from": "/path/s3.secret"},
"role": "peer",
"after": ["<unit>.service"]
}
```
Validation relaxes the old "one mail server only" refusal: multiple servers are allowed **iff every** mail node carries a cluster block (a clustered install); a mix is still refused.
## `inbuxa cluster join -f FILE`
Acts on this machine's block only — it never reaches another node; the file is copied across and run on each, like the rest of the installer.
1. Install the secrets every node reads from disk (store / coordinator / blob), each `0400`, owned by the server user. A secret with `secret_from` is installed from it; one without must already be in place.
2. Keep the current `config.json` aside once as `config.json.prev` (rollback), then point the server at the shared store.
3. Write the `cluster.conf` drop-in (`INBUXA_HOSTNAME`, and `INBUXA_ROLE` unless this is the node that carries every task) and, when `after` is set, `cluster-order.conf` (`After=`/`Wants=`).
4. `daemon-reload` and restart.
`--dry-run` prints every file it would write, with contents, and stops. The real run needs `--yes` and root.
### Scope — node half only (by design)
This configures a node joining an **already-initialised** cluster. A joining node reads the blob store and coordinator **definitions** from the shared store the moment its config points there; all it needs locally is the store config and the `File` secrets those definitions reference — which is exactly what this writes. Seeding the shared registry (the `x:BlobStore` / `x:Coordinator` / `x:ClusterRole` objects) is the one-time cluster-**creation** step, not something each node repeats, and it carries tuning that doesn't belong hard-coded in a general installer; it's left out here deliberately. The schema still names the coordinator/blob endpoints so the file is complete and their secrets land beside the store's.
## Tests & checks
New: `internal/cluster/join_test.go` (plan build, config.json shape, secret install + modes, drop-in contents, rollback copy, dry-run writes nothing, missing/preexisting secret), `internal/topology/cluster_test.go` (v1 still valid, cluster needs v2, must run a server, clustered multi-server, field validation). Full `go test ./...`, `go vet` (amd64 + arm64), `gofmt`, and the stdlib-only check all pass locally. No new dependencies — stdlib only.
Not merged; opening for review.
jcoffey-dev
changed target branch from feat/cluster-doctor to main2026-11-12 14:02:11 +00:00
Topology version 2 adds an optional cluster block to a server machine:
where this node reaches the shared SQL store, the coordinator and the
blob store, what role it takes, and what it must start after. Every
address in it is the operator's; the installer bakes in none of its own,
and a file with no cluster block is read exactly as before.
inbuxa cluster join -f FILE acts on this machine's block: it installs the
secrets every node reads from disk, points the server at the shared store
(keeping the old config.json aside for rollback), writes the hostname,
role and boot-order drop-ins, and restarts. --dry-run prints every file
it would write and stops. It is the node's half only; the shared registry
that names the blob store and coordinator is set up once per cluster, not
by each node that joins.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Stacks on #53 (
cluster doctor) — merge that first; this branch is based onfeat/cluster-doctor, so the diff here is just the join half.This is #2 of the 27.1 tooling roadmap: guided cluster membership.
doctor(#53) was the read-only reachability preflight; this is the node-side configuration that follows it.Topology v2
A server machine may now carry an optional
clusterblock. It names where this node reaches the shared SQL store, the coordinator and the blob store, what role it takes, and what units it must start after. Every address in it is the operator's — the installer bakes in none of its own, and a file with no cluster block is read exactly as a v1 file was.Loadaccepts versions 1 and 2; a cluster block requires version 2.Validation relaxes the old "one mail server only" refusal: multiple servers are allowed iff every mail node carries a cluster block (a clustered install); a mix is still refused.
inbuxa cluster join -f FILEActs on this machine's block only — it never reaches another node; the file is copied across and run on each, like the rest of the installer.
0400, owned by the server user. A secret withsecret_fromis installed from it; one without must already be in place.config.jsonaside once asconfig.json.prev(rollback), then point the server at the shared store.cluster.confdrop-in (INBUXA_HOSTNAME, andINBUXA_ROLEunless this is the node that carries every task) and, whenafteris set,cluster-order.conf(After=/Wants=).daemon-reloadand restart.--dry-runprints every file it would write, with contents, and stops. The real run needs--yesand root.Scope — node half only (by design)
This configures a node joining an already-initialised cluster. A joining node reads the blob store and coordinator definitions from the shared store the moment its config points there; all it needs locally is the store config and the
Filesecrets those definitions reference — which is exactly what this writes. Seeding the shared registry (thex:BlobStore/x:Coordinator/x:ClusterRoleobjects) is the one-time cluster-creation step, not something each node repeats, and it carries tuning that doesn't belong hard-coded in a general installer; it's left out here deliberately. The schema still names the coordinator/blob endpoints so the file is complete and their secrets land beside the store's.Tests & checks
New:
internal/cluster/join_test.go(plan build, config.json shape, secret install + modes, drop-in contents, rollback copy, dry-run writes nothing, missing/preexisting secret),internal/topology/cluster_test.go(v1 still valid, cluster needs v2, must run a server, clustered multi-server, field validation). Fullgo test ./...,go vet(amd64 + arm64),gofmt, and the stdlib-only check all pass locally. No new dependencies — stdlib only.Not merged; opening for review.
4835d2ebc1to15fdb171fe