Pim van Pelt
744b1cb3d2
Makefile:
- New install-deps umbrella target split into three sub-targets:
install-deps-apt — Debian/Trixie-packaged build deps
(nodejs, npm, protobuf-compiler, git, make,
dpkg-dev, ca-certificates, curl, tar). Uses
sudo when not already root.
install-deps-go — ensures a Go toolchain >= GO_VERSION (go.mod
floor, default 1.25.0). Short-circuits when
the system Go is already recent enough;
otherwise downloads the upstream tarball
from go.dev/dl/ into /usr/local/go. Trixie
only ships 1.24 so this step is load-bearing.
install-deps-go-tools — go install protoc-gen-go, protoc-gen-go-grpc,
and golangci-lint/v2/cmd/golangci-lint. Then
asserts the installed golangci-lint version
parses as >= GOLANGCI_LINT_VERSION (default
1.64.0, the floor that supports Go 1.25
syntax) to catch stale binaries in $GOPATH
/bin before they silently run against Go
1.25 code.
- Parser bug fixed: golangci-lint v1.x prints "has version v1.64.8" but
v2.x dropped the 'v' prefix and prints "has version 2.11.4". The
original sed regex required the 'v' and returned an empty match on
v2.x, making the assertion explode with "could not parse version
output". Fixed by switching to extended regex (sed -En) with 'v?' so
both forms parse cleanly.
- GO_VERSION and GOLANGCI_LINT_VERSION exposed as Makefile variables
so operators can override on the command line, e.g.
make install-deps GO_VERSION=1.25.5 GOLANGCI_LINT_VERSION=2.0.0
- .PHONY extended with the four new target names.
Docs:
- README.md: capability note rewritten to cover CAP_NET_RAW (ICMP) and
the new CAP_SYS_ADMIN requirement when healthchecker.netns is set,
plus a paragraph explaining that the Debian systemd unit grants both
automatically. Docker example gained a second variant that shows the
additional --cap-add SYS_ADMIN and /var/run/netns bind mount for
netns-scoped deployments. Also notes that maglevd-frontend ignores
SIGHUP so controlling-terminal disconnects don't kill it.
- docs/user-guide.md: Capabilities section rewritten as a bulleted
list covering both caps, with the EPERM error string and three
different ways to grant them (systemd unit, setcap, systemd-run);
'show vpp lb counters' command description updated to explain that
per-backend packet counts are no longer shown (LB plugin's
forwarding node bypasses ip{4,6}_lookup_inline, so /net/route/to at
the backend's FIB entry never ticks for LB-forwarded traffic); new
~75-line "What the SPA shows" subsection covering the scope
selector + maglev_scope cookie, the per-maglevd frontend cards, the
health-cascade icon table (ok / bug-buckets / primary-drained /
degraded / unknown), the lb buckets column semantics, the
maglev_zippy_open cookie, the admin-mode lifecycle dialogs with
their plain-English consequence text, and the debug panel.
- docs/config-guide.md: healthchecker.netns field gains a capability-
requirement note spelling out setns(CLONE_NEWNET), the EPERM
symptom string, and the /var/run/netns/ readability requirement.
- docs/healthchecks.md: new "Jitter" subsection explaining the +/-10%
scaling on every computed interval, and a "Probe timing while a
probe is in flight" subsection that explains why fast-interval alone
doesn't give fast fault detection against hanging backends (the
probe loop is synchronous, so each iteration is timeout +
fast-interval; the advice is to lower timeout, not fast-interval).
- docs/maglevd.8: description paragraph corrected (dropped the
per-backend stats claim and added a short note pointing at the LB
plugin forwarding-path bypass); new CAPABILITIES section between
SIGNALS and FILES covering both CAP_NET_RAW and CAP_SYS_ADMIN with
the drop-in-override hint.
- docs/maglevd-frontend.8: new SIGNALS section documenting the
explicit SIGHUP ignore (so a controlling-terminal disconnect doesn't
kill the daemon); description extended with paragraphs on the two
persistence cookies (maglev_scope, maglev_zippy_open) and on the
health-cascade icon + lb buckets column.
- docs/maglevc.1: left untouched — intentionally minimal and delegates
to docs/user-guide.md.
Lint (26 issues across 12 files, all errcheck / ineffassign / S1021):
- cmd/frontend/handlers.go: _, _ = fmt.Fprintf(...) for the SSE retry
hint and resync control-event writes.
- cmd/maglevc/commands.go: bulk-prefix every fmt.Fprintf(w, ...) with
_, _ =; also merged 'var watchEventsOptSlot *Node; ... = &Node{...}'
into a single := declaration (staticcheck S1021) — the self-
referencing pattern still works because the Children back-ref is
assigned on the next statement, not inside the struct literal.
- cmd/maglevc/complete.go: _, _ = fmt.Fprintf(ql.rl.Stderr(), ...)
for the banner and help writes; removed the ineffectual
'partial = ""' assignment (nothing downstream reads partial after
that branch, so setting it was dead code flagged by ineffassign).
- cmd/maglevc/shell.go: defer func() { _ = rl.Close() }() for the
readline instance; _, _ = fmt.Fprintf(rl.Stderr(), ...) for error
display in the REPL loop.
- cmd/maglevc/main.go: defer func() { _ = conn.Close() }() for the
gRPC client connection.
- internal/grpcapi/server_test.go: _ = conn.Close() in the test
teardown closure.
- internal/prober/http.go: _ = c.Close() in the TLS-handshake-failed
path; defer func() { _ = conn.Close() }() and defer func() { _ =
resp.Body.Close() }() for the two deferred cleanups.
- internal/prober/http_test.go: defer func() { _ = resp.Body.Close()
}() plus three _, _ = fmt.Fprint(w, ...) in the httptest.Server
handlers and _, _ = fmt.Sscanf(...) when parsing the test listener's
port.
- internal/prober/icmp.go: defer func() { _ = pc.Close() }() for the
ICMP packet conn.
- internal/prober/netns.go: defer func() { _ = origNs.Close() }(),
defer func() { _ = netns.Set(origNs) }(), defer func() { _ =
targetNs.Close() }() — also dropped a stray //nolint:errcheck that
was no longer needed once the closure wrapping handled the discard.
- internal/prober/tcp.go: _ = conn.Close() in the L4-only path,
_ = tlsConn.Close() in the failed and succeeded handshake branches,
_ = tlsConn.SetDeadline(...) (also dropped a //nolint:errcheck
previously covering it).
Iterative 'make lint' runs were needed because golangci-lint v2.x
caps same-linter reports per pass, so the first pass reported 21,
then 4, then 3, then 1, then 0. Final pass: 0 issues. make test is
green across every package, and make build produces all three
binaries cleanly.
118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# vpp-maglev
|
|
|
|
Health checker, gRPC control plane, CLI, and web dashboard for the VPP
|
|
`lb` (load-balancer) plugin. Runs as a set of three binaries under one
|
|
Debian package:
|
|
|
|
- **`maglevd`** — the long-running health-checker daemon. Probes backends
|
|
(HTTP, TCP, ICMP), tracks their aggregate state, programs the VPP
|
|
dataplane via the `lb` plugin binary API, and exposes everything
|
|
over a gRPC API + Prometheus `/metrics` endpoint.
|
|
- **`maglevc`** — the interactive CLI client. Tab-completing shell with
|
|
inline help; also runs one-shot commands for scripting.
|
|
- **`maglevd-frontend`** — optional web dashboard. One binary with a
|
|
SolidJS Single-Page-App; connects to one or more maglevds over gRPC and
|
|
serves a live HTTP view (read-only `/view/` and optional basic-auth
|
|
`/admin/` with mutating commands).
|
|
|
|
## Build and install
|
|
|
|
```sh
|
|
make install-deps # installs all build-time dependencies
|
|
make # builds build/<arch>/ binaries
|
|
make test # runs all tests
|
|
make pkg-deb # creates a Debian package for amd64 and arm64
|
|
```
|
|
|
|
Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go`
|
|
and `protoc-gen-go-grpc`. The SolidJS bundle under
|
|
`cmd/frontend/web/` is built automatically via `make` through the
|
|
`maglevd-frontend-web` target, which needs `npm`.
|
|
|
|
Produces `vpp-maglev_<version>_amd64.deb` and
|
|
`vpp-maglev_<version>_arm64.deb` in the `build/` directory by
|
|
cross-compiling with `GOOS=linux GOARCH=<arch>`. Requires `dpkg-deb`
|
|
(available on any Debian/Ubuntu host). The installed binaries report
|
|
the exact git commit via `maglevd --version` (and similarly for
|
|
`maglevc` / `maglevd-frontend`).
|
|
|
|
## Running
|
|
|
|
After installing, `maglevd` is enabled automatically but
|
|
`maglevd-frontend` is **not** — it's opt-in, so the web dashboard
|
|
doesn't surprise anyone who just wanted the daemon:
|
|
|
|
```sh
|
|
# edit /etc/vpp-maglev/maglev.yaml, then:
|
|
systemctl enable --now vpp-maglev
|
|
|
|
# optional: web dashboard. Edit /etc/default/vpp-maglev to set
|
|
# MAGLEV_FRONTEND_ARGS and (optionally) MAGLEV_FRONTEND_USER /
|
|
# MAGLEV_FRONTEND_PASSWORD for /admin/ access, then:
|
|
systemctl enable --now vpp-maglev-frontend
|
|
```
|
|
|
|
Or run the components by hand:
|
|
|
|
```sh
|
|
maglevd --config /etc/vpp-maglev/maglev.yaml --grpc-addr :9090
|
|
maglevd --version # print version and exit
|
|
|
|
maglevc --server localhost:9090 # interactive shell
|
|
maglevc show frontends # one-shot
|
|
maglevc -color=false show backends # one-shot, no ANSI color
|
|
maglevc set backend nginx0-ams pause
|
|
|
|
maglevd-frontend -server localhost:9090 -listen :8080
|
|
```
|
|
|
|
Send `SIGHUP` to `maglevd` to reload config without restarting.
|
|
`maglevd` requires:
|
|
|
|
- `CAP_NET_RAW` for ICMP health checks (raw sockets).
|
|
- `CAP_SYS_ADMIN` when `healthchecker.netns` is set so probes can
|
|
`setns(CLONE_NEWNET)` into the dataplane namespace. Without it,
|
|
every probe errors out with `enter netns "<name>": operation not
|
|
permitted`.
|
|
|
|
The Debian systemd unit grants both via `AmbientCapabilities` /
|
|
`CapabilityBoundingSet`, so `systemctl start vpp-maglev` works out
|
|
of the box. When running by hand under a non-root user, grant them
|
|
via `setcap cap_net_raw,cap_sys_admin=eip /usr/sbin/maglevd` or
|
|
equivalent.
|
|
|
|
`maglevd-frontend` also ignores `SIGHUP` so a controlling-terminal
|
|
disconnect (e.g. closing the SSH session it was started from)
|
|
doesn't kill the daemon; `SIGTERM` / `SIGINT` remain the clean
|
|
shutdown signals.
|
|
|
|
Every flag on every binary also has an environment-variable
|
|
equivalent (e.g. `MAGLEV_CONFIG`, `MAGLEV_GRPC_ADDR`,
|
|
`MAGLEV_SERVERS`, `MAGLEV_LISTEN`, `MAGLEV_LOG_LEVEL`) so all three
|
|
programs can be driven entirely via env in containerized
|
|
deployments.
|
|
|
|
## Documentation
|
|
|
|
- A minimal configuration file in
|
|
[debian/maglev.yaml](debian/maglev.yaml) shows every knob.
|
|
- [docs/user-guide.md](docs/user-guide.md) — flags, signals, and
|
|
`maglevc` command reference.
|
|
- [docs/config-guide.md](docs/config-guide.md) — full YAML reference.
|
|
- [docs/healthchecks.md](docs/healthchecks.md) — health state
|
|
machine, probe scheduling, rise/fall semantics.
|
|
- Manpages: `maglevd(8)`, `maglevc(1)`, `maglevd-frontend(8)`.
|
|
|
|
## Docker
|
|
|
|
```sh
|
|
docker build -t maglevd .
|
|
docker run --cap-add NET_RAW \
|
|
-v /etc/vpp-maglev:/etc/vpp-maglev maglevd
|
|
|
|
# With netns-scoped health checks (maglev.yaml sets healthchecker.netns):
|
|
docker run --cap-add NET_RAW --cap-add SYS_ADMIN \
|
|
-v /etc/vpp-maglev:/etc/vpp-maglev \
|
|
-v /var/run/netns:/var/run/netns maglevd
|
|
```
|