ipng/vpp-maglev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

install-deps Makefile target; docs refresh; golangci-lint v2 clean

Browse Source 
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.
This commit is contained in:
Pim van Pelt
2026-04-14 17:37:43 +02:00
parent 224167ce39
commit 744b1cb3d2
18 changed files with 502 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@@ -10,17 +10,18 @@ Debian package:
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 the
SolidJS SPA embedded via `//go:embed`; connects to one or more
maglevds over gRPC and serves a live HTTP view (read-only `/view/`
and optional basic-auth `/admin/`).
- **`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 # builds build/<arch>/{maglevd,maglevc,maglevd-frontend}
make test # runs all tests
make pkg-deb # creates a Debian package for amd64 and arm64
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`
@@ -66,7 +67,24 @@ 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.
`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`,
@@ -89,5 +107,11 @@ deployments.
```sh
docker build -t maglevd .
docker run --cap-add NET_RAW -v /etc/vpp-maglev:/etc/vpp-maglev 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
```