Pools, CLI, versioning, Debian packaging, HTTPS fix
- Replaced flat `backends: [...]` list on frontends with an ordered `pools:`
list; each pool has a name and a map of backends with per-pool weights (0–100,
default 100). Pools express priority: first pool with a healthy backend wins.
- Removed global backend weight (was on the backend, now lives in the pool).
- Config validation enforces non-empty pools, non-empty pool names, weight
range, and consistent address families across all pools of a frontend.
- Added `PoolBackendInfo { name, weight }` and changed `PoolInfo.backends` from
`repeated string` to `repeated PoolBackendInfo` so weights are visible over
the API.
- Full interactive shell with readline, tab completion, and `?` inline help.
- Command tree parser (Walk) handles fixed keywords and dynamic slot nodes;
prefix matching with exact-match priority.
- Commands: `show version/frontends/frontend/backends/backend/healthchecks/
healthcheck`, `set backend <name> pause|resume`, `quit`/`exit`.
- `show frontend` output is hierarchical (pools → backends) with per-backend
weights and `[disabled]` notation; pool section uses fixed-width formatting
so ANSI color codes don't corrupt tabwriter alignment.
- `-color` flag (default true) wraps static field labels in dark-blue ANSI;
works correctly with tabwriter because all labels carry identical-length
escape sequences.
- `cmd/version.go` package holds `version`, `commit`, `date` vars set at build
time via `-ldflags -X`.
- `make build` / `make build-amd64` / `make build-arm64` all inject
`VERSION=0.1.1`, `COMMIT_HASH` (from `git rev-parse --short HEAD`), and
`DATE` (UTC ISO-8601).
- `maglevc` prints version on interactive startup and exposes `show version`.
- `maglevd` logs version/commit/date at startup; `-version` flag prints and exits.
- `doHTTPProbe` was building a `https://` target URL even though TLS was already
applied to the connection inside `inNetns`. `http.Transport` then wrapped the
connection in a second TLS layer, producing "http: server gave HTTP response
to HTTPS client". Fixed by always using `http://` in the target URL.
- Added `TestHTTPSProbe` using `httptest.NewTLSServer` to cover the full path.
- New `docs/user-guide.md`: maglevd flags/signals, maglevc commands, shell
completion, and command-tree parser walkthrough.
- New `docs/healthchecks.md`: state machine, rise/fall model, probe intervals,
all transition events with log examples.
- Updated `docs/config-guide.md`: pools design, removed global weight from
backends, updated all examples.
- Updated `README.md`: packaging table, build paths, corrected binary locations
(`/usr/sbin/maglevd`), config filename (`.yaml`).
- `debian/` directory contains `control.in`, `maglevd.service`, `default.maglev`,
`maglev.yaml` (example config), `conffiles`, `postinst`, `prerm`.
- `debian/build-deb.sh` stages a package tree and calls `dpkg-deb`; emits
`build/vpp-maglev_<version>~<commit>_<arch>.deb`.
- Cross-compiles for amd64 and arm64 in one `make pkg-deb` invocation.
- `maglevd` installed to `/usr/sbin/`, `maglevc` to `/usr/bin/`.
- Service reads `MAGLEV_CONFIG` from `/etc/default/maglev`
(default: `/etc/maglev/maglev.yaml`).
- Man pages `maglevd(8)` and `maglevc(1)` live in `docs/` and are gzip'd into
the package.
- All build output goes to `build/<arch>/`; `build/` is gitignored.
This commit is contained in:
133
docs/user-guide.md
Normal file
133
docs/user-guide.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# User Guide
|
||||
|
||||
## maglevd
|
||||
|
||||
`maglevd` is the health-checker daemon. It probes backends according to the
|
||||
configuration file, maintains their health state, and exposes a gRPC API for
|
||||
inspection and control.
|
||||
|
||||
### Flags
|
||||
|
||||
| Flag | Environment variable | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `--config` | `MAGLEV_CONFIG` | `/etc/maglev/maglev.yaml` | Path to the YAML configuration file. |
|
||||
| `--grpc-addr` | `MAGLEV_GRPC_ADDR` | `:9090` | TCP address on which the gRPC server listens. |
|
||||
| `--log-level` | `MAGLEV_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, or `error`. |
|
||||
| `--version` | — | — | Print version, commit hash, and build date, then exit. |
|
||||
|
||||
Flags take precedence over environment variables. Both are optional; defaults
|
||||
are used for anything not set.
|
||||
|
||||
### Signals
|
||||
|
||||
| Signal | Effect |
|
||||
|---|---|
|
||||
| `SIGHUP` | Reload the configuration file. New backends are started, removed backends are stopped, backends whose health-check config is unchanged continue probing without interruption. |
|
||||
| `SIGTERM` / `SIGINT` | Graceful shutdown. Active gRPC streams are closed, the server drains, then the process exits. |
|
||||
|
||||
### Capabilities
|
||||
|
||||
`maglevd` requires `CAP_NET_RAW` when any health check uses `type: icmp`.
|
||||
All other check types (`tcp`, `http`) use normal TCP sockets and require no
|
||||
special capabilities.
|
||||
|
||||
### Logging
|
||||
|
||||
All log output is written to stdout as JSON using Go's `log/slog`. The first
|
||||
line logged after the logger is configured is a `starting` record that includes
|
||||
`version`, `commit`, and `date`. Every state change emits a `backend-transition`
|
||||
line at `INFO` level. Set `--log-level debug` to see individual probe attempts
|
||||
and their outcomes.
|
||||
|
||||
---
|
||||
|
||||
## maglevc
|
||||
|
||||
`maglevc` is the interactive control-plane client. It connects to a running
|
||||
`maglevd` over gRPC and either executes a single command or drops into an
|
||||
interactive shell.
|
||||
|
||||
### Usage
|
||||
|
||||
```sh
|
||||
maglevc [--server host:port] [--color[=bool]] [command...]
|
||||
```
|
||||
|
||||
| Flag | Default | Description |
|
||||
|---|---|---|
|
||||
| `--server` | `localhost:9090` | Address of the `maglevd` gRPC server. |
|
||||
| `--color` | `true` | Colorize static field labels in output (dark blue ANSI). Pass `--color=false` to disable, e.g. when piping. |
|
||||
|
||||
When `command` arguments are supplied the command is executed and `maglevc`
|
||||
exits. When no arguments are given an interactive shell is started and the
|
||||
build version is printed on entry.
|
||||
|
||||
### Commands
|
||||
|
||||
```
|
||||
show version Print build version, commit hash, and build date.
|
||||
|
||||
show frontends List all frontend names.
|
||||
show frontend <name> Show address, protocol, port, description, and pools.
|
||||
Each pool lists its backends with weights (if != 100)
|
||||
and marks disabled backends with [disabled].
|
||||
|
||||
show backends List all backend names.
|
||||
show backend <name> Show address, current state (with duration in that state),
|
||||
enabled flag, health check, and recent state transitions
|
||||
with timestamps and how long ago each occurred.
|
||||
|
||||
show healthchecks List all health-check names.
|
||||
show healthcheck <name> Show full health-check configuration.
|
||||
|
||||
set backend <name> pause Suspend health checking for a backend, freezing its state.
|
||||
set backend <name> resume Resume health checking; backend re-enters unknown state
|
||||
and is probed immediately.
|
||||
|
||||
quit / exit Leave the interactive shell.
|
||||
```
|
||||
|
||||
### Interactive shell
|
||||
|
||||
The shell prompt is `maglev> `. Two completion mechanisms are available:
|
||||
|
||||
**Tab completion** — pressing `<Tab>` at any point completes the current token.
|
||||
Fixed keywords (commands and subcommands) are completed from the command tree.
|
||||
Backend, frontend, and health-check names are fetched live from the server with
|
||||
a 1-second timeout. If the partial token is unambiguous the word is completed
|
||||
in place; if multiple candidates exist they are listed and the prompt is
|
||||
restored.
|
||||
|
||||
**Inline help (`?`)** — typing `?` at any point prints the available
|
||||
completions for the current position, with a short description next to each
|
||||
keyword. The `?` character is not added to the input line.
|
||||
|
||||
Commands and keywords support **prefix matching**: typing `sh b` is equivalent
|
||||
to `show backend` provided the prefix is unambiguous. Exact matches always take
|
||||
priority over prefix matches, so `show backend` and `show backends` are
|
||||
unambiguous even though one is a prefix of the other.
|
||||
|
||||
### Command tree and parser
|
||||
|
||||
Commands form a tree of `Node` values. Each node has a fixed `Word` (a keyword)
|
||||
or is a *slot node* (marked by a `Dynamic` function that enumerates valid
|
||||
values at completion time). The parser (`Walk`) descends the tree token by
|
||||
token:
|
||||
|
||||
1. Try to match the current token against the fixed-keyword children of the
|
||||
current node (exact match first, then unique prefix match).
|
||||
2. If no fixed child matches, try a slot child — any token is accepted and
|
||||
stored as an argument.
|
||||
3. Stop when tokens are exhausted or no match is found.
|
||||
|
||||
The leaf node reached by `Walk` must have a `Run` function; otherwise the
|
||||
available sub-commands at that position are printed as help. Arguments
|
||||
collected from slot nodes are passed to `Run` as a slice.
|
||||
|
||||
Example walk for `set backend nginx0-ams pause`:
|
||||
|
||||
```
|
||||
root → set → backend → <name>(nginx0-ams collected as arg) → pause
|
||||
```
|
||||
|
||||
`pause.Run` is called with `args = ["nginx0-ams"]`.
|
||||
Reference in New Issue
Block a user