docs: fix genuine passive-voice hits in docs/swarm
Read all 94 write-good.Passive hits across docs/swarm/ (ca.md, README.md, secrets.md, services.md, sso.md, ui.md) in context. 44 are genuine catches with a nameable, usually already-established actor (swarm-controller, authelia, swarmctl, the controller, the gateway, this module, hyperhive itself, or 'the operator' for manual actions) — rewritten to active. 50 are legitimate passives or false catches, left alone: predicate-adjective state descriptions (is expected/misconfigured/ broken), negative-capability idioms (no X is needed/placed, can't be Yed/listed/fetched), config-state conditionals (whenever/when X is enabled/configured/set), requirement-list labels (is required), 'is tracked as' idiom, backward-looking changelog facts with no actor (was removed/verified/introduced), ambiguous-actor statements left conservatively alone (agents are created and destroyed — could be hive-c0re or swarm-controller, doc doesn't say), and a couple of deliberately-parallel idiom pairs. Several sibling-inconsistency fixes: a passive clause sitting next to an already-active sibling describing the same fact/mechanism (ca.md's two-bullet consumer list, README's 4-item WireGuard-mesh bullet list, README's controller-registers-hooks paragraph, sso.md's followed-a-302 sentence). Verified via vale on the whole directory, diffed against main's exact baseline (not just the Passive count): write-good.Passive 94 -> 50 exactly, every other category unchanged (1 pre-existing Microsoft.Contractions error at services... at secrets.md:182, 8 TooWordy, 1 Microsoft.We, 1 Microsoft.FirstPerson — same counts, same locations).
This commit is contained in:
iris
mara
parent
e9d59f3d10
commit
fab2a0dedc
6 changed files with 79 additions and 78 deletions
|
|
@ -16,8 +16,8 @@ sections below don't repeat it, so a service that stops deriving is a
|
|||
visible difference rather than one more paragraph saying the same thing.
|
||||
|
||||
`singleHostSwarm` is the all-on-one-box switch above it: it defaults
|
||||
both `deploy.allSwarmServices` and `swarm.ca.autoConfigure` (the swarm CA
|
||||
is generated here). Each derived toggle can still be set on its own,
|
||||
both `deploy.allSwarmServices` and `swarm.ca.autoConfigure` (this host
|
||||
generates the swarm CA here). Each derived toggle can still be set on its own,
|
||||
which wins, so "all local except X" needs no further option.
|
||||
|
||||
**Both default to off**, and that's deliberate: a host can't tell
|
||||
|
|
@ -45,8 +45,8 @@ the shapes worth naming are the ones they produce:
|
|||
- **Fully spread out.** One container / VM / machine per service,
|
||||
somewhere.
|
||||
|
||||
**These are a set, not a ladder with a correct top, and in-between
|
||||
shapes are supported.** Each derived toggle can be set on its own (see
|
||||
**These are a set, not a ladder with a correct top, and hyperhive
|
||||
supports in-between shapes.** Each derived toggle can be set on its own (see
|
||||
above), which is what makes "all local except X" a configuration rather
|
||||
than an unsupported edge case. Nothing in hyperhive prescribes a
|
||||
deployment model, so a doc that treats one shape as the real one and
|
||||
|
|
@ -69,21 +69,21 @@ provider, differentiated by roles and claims rather than by mechanism —
|
|||
there is one IdP and one auth path.
|
||||
|
||||
- **`deploy.authelia`** — run the container here.
|
||||
- **`swarm.authelia.url`** — where clients are sent to authenticate.
|
||||
- **`swarm.authelia.url`** — where clients go to authenticate.
|
||||
Present on **every** hive, defaulting to this host's own instance only
|
||||
when this module is the thing running it; otherwise `null`, and a hive
|
||||
joining someone else's swarm sets it explicitly. Null means "no SSO
|
||||
configured", and consumers say so rather than guessing an address.
|
||||
|
||||
The users database is written by swarm-controller, not by hand: agents
|
||||
swarm-controller writes the users database, not by hand: agents
|
||||
are created and destroyed continuously, so the subject set is dynamic.
|
||||
This module only guarantees the file exists and parses, so authelia
|
||||
starts with nobody in it rather than failing to start — a provider with
|
||||
no subjects yet is the correct state before anything has provisioned
|
||||
them. Session and storage keys are generated in the container on first
|
||||
boot and never rotated automatically; replacing one invalidates data
|
||||
already written (sessions, the encrypted store), so that's an operator
|
||||
action.
|
||||
them. Authelia generates session and storage keys in the container on
|
||||
first boot and never rotates them automatically; replacing one
|
||||
invalidates data already written (sessions, the encrypted store), so
|
||||
that's an operator action.
|
||||
|
||||
Storage is local sqlite and the notifier writes to a file. Both are
|
||||
small-deployment choices, and the scope is the justification: redis
|
||||
|
|
@ -91,13 +91,13 @@ buys shared session state across replicas and there is one instance;
|
|||
SMTP exists to mail humans, and provisioning here is programmatic.
|
||||
|
||||
See [`sso.md`](sso.md) for bootstrapping the first user and the OIDC
|
||||
relying-party flow, and [`secrets.md`](secrets.md) for where each of
|
||||
authelia's keys is generated and read.
|
||||
relying-party flow, and [`secrets.md`](secrets.md) for where authelia
|
||||
generates and reads each of its keys.
|
||||
|
||||
### Metrics (VictoriaMetrics + Grafana)
|
||||
|
||||
The swarm's telemetry lands in one VictoriaMetrics and is read through
|
||||
one Grafana, in two containers at `metrics.<swarm-domain>` and
|
||||
The swarm's telemetry lands in one VictoriaMetrics, and one Grafana
|
||||
reads it, in two containers at `metrics.<swarm-domain>` and
|
||||
`grafana.<swarm-domain>`. Two containers rather than one so Grafana can
|
||||
be restarted or broken without taking the time-series database with it.
|
||||
|
||||
|
|
@ -119,8 +119,8 @@ See `retentionPeriod` below before leaving it at its default.
|
|||
| `deploy.grafana.datasourceUrl` | Only if you front VictoriaMetrics with something else. It defaults to the store on this host, which is the only thing it can reach. |
|
||||
|
||||
**Logging in.** Grafana is behind swarm SSO, so the accounts are the
|
||||
authelia ones — there is no separate Grafana password, and the local
|
||||
login form is switched off whenever SSO is configured. If you enable
|
||||
authelia ones — there is no separate Grafana password, and this module
|
||||
switches off the local login form whenever SSO is configured. If you enable
|
||||
Grafana on a host with no authelia, the form stays on and Grafana's
|
||||
default `admin`/`admin` applies; change it before exposing that host.
|
||||
|
||||
|
|
@ -178,9 +178,9 @@ gateway either way.
|
|||
| `swarm.otel.domain` | Only to rename it — the default already resolves correctly for every hive in the swarm. |
|
||||
| `swarm.otel.port` | Only if something else on the services host already claims `4319`. |
|
||||
|
||||
With neither `otel.endpoint` nor the store enabled, this collector is
|
||||
refused at eval — a tier that receives samples and drops them looks
|
||||
healthy while losing data.
|
||||
With neither `otel.endpoint` nor the store enabled, this module refuses
|
||||
the collector at eval — a tier that receives samples and drops them
|
||||
looks healthy while losing data.
|
||||
|
||||
Agent-side configuration, and what a hive's own collector does, are in
|
||||
[`../scheduler/observability.md`](../scheduler/observability.md).
|
||||
|
|
|
|||
Loading…
Reference in a new issue