Pim van Pelt
bc6ccaa844
Bump VERSION to 1.0.0 and cut the first tagged release of vpp-maglev. Also in this commit: - maglevc: MAGLEV_SERVER env var as an alternative to the --server flag, matching the MAGLEV_CONFIG / MAGLEV_GRPC_ADDR convention on the other binaries. The flag takes precedence when both are set. - Rename cmd/maglevd -> cmd/server and cmd/maglevc -> cmd/client so the source directory names are decoupled from binary names (the frontend and tester commands already followed this convention). Build outputs and the Debian packages are unchanged.
127 lines
5.0 KiB
Markdown
127 lines
5.0 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, plus an out-of-band tester built alongside:
|
|
|
|
- **`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).
|
|
- **`maglevt`** — optional out-of-band VIP probe TUI. Reads a
|
|
`maglev.yaml` and hits each frontend on a live HTTP path, reporting
|
|
latency and a configurable response-header tally so operators can see
|
|
failover as it happens. Does not talk gRPC; useful for validating a
|
|
`maglevd` restart end-to-end from a client perspective. Built by
|
|
`make` but not installed by the Debian package.
|
|
|
|
## 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_SERVER`,
|
|
`MAGLEV_SERVERS`, `MAGLEV_LISTEN`, `MAGLEV_LOG_LEVEL`) so all three
|
|
programs can be driven entirely via env in containerized
|
|
deployments.
|
|
|
|
## Documentation
|
|
|
|
- [docs/design.md](docs/design.md) — architecture, components, and
|
|
numbered functional / non-functional requirements. Start here if
|
|
you want the big picture before diving into the code.
|
|
- 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
|
|
```
|