Add WatchEvents, enable/disable/weight RPCs, and config check

gRPC / proto
- Rename WatchBackendEvents → WatchEvents; return a stream of Event
  oneof (LogEvent, BackendEvent, FrontendEvent) with optional filter
  flags (log, log_level, backend, frontend)
- Add EnableBackend, DisableBackend, SetFrontendPoolBackendWeight RPCs
- Rename PauseResumeRequest → BackendRequest
- Add CheckConfig RPC returning ok/parse_error/semantic_error

maglevd
- Route slog through a LogBroadcaster (slog.Handler) so WatchEvents
  subscribers can receive structured log records independently of the
  daemon's own --log-level
- Add --reflection flag (default true) to toggle gRPC server reflection
- Add --check flag: validates config file and exits 0/1/2
- SIGHUP: use config.Check before applying reload; log parse vs semantic
  error separately; refuse reload on any error
- Rename default config path /etc/maglev → /etc/vpp-maglev

maglevc
- Add 'watch events [num <n>] [log [level <level>]] [backend] [frontend]'
  command; prints compact protojson, stops on any keypress or Ctrl-C;
  uses cbreak mode (not raw) so output post-processing is preserved
- Add 'set backend <name> enable|disable'
- Add 'set frontend <name> pool <pool> backend <name> weight <0-100>'
- Add 'config check' command

Debian packaging
- Rename service unit to vpp-maglevd.service
- Rename conffiles to /etc/default/vpp-maglev and /etc/vpp-maglev/
- Create maglevd system user/group in postinst; add to vpp group if present
- Add postrm; add adduser to Depends
This commit is contained in:
2026-04-11 16:42:11 +02:00
parent d612086a5f
commit 58391f5463
26 changed files with 1969 additions and 400 deletions

View File

@@ -2,55 +2,38 @@
Health checker and gRPC control plane for VPP Maglev load balancing.
## Build
## Build and Install
```sh
make # builds build/<arch>/maglevd and build/<arch>/maglevc
make test # runs all tests
make proto # regenerates gRPC stubs from proto/maglev.proto
make lint # runs golangci-lint
make pkg-deb # Creates a debian package for arm64 and amd64
```
Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go` and
`protoc-gen-go-grpc`.
## Debian package
```sh
make pkg-deb
```
Produces `vpp-maglev_<version>_amd64.deb` and `vpp-maglev_<version>_arm64.deb`
in the project root by cross-compiling with `GOOS=linux GOARCH=<arch>`.
in the `build/` directory by cross-compiling with `GOOS=linux GOARCH=<arch>`.
Requires `dpkg-deb` (available on any Debian/Ubuntu host).
The package installs:
| Path | Content |
|---|---|
| `/usr/sbin/maglevd` | Health-checker daemon |
| `/usr/bin/maglevc` | Interactive CLI client |
| `/lib/systemd/system/maglevd.service` | systemd unit |
| `/etc/default/maglev` | Environment file for the unit (conffile) |
| `/etc/maglev/maglev.yaml` | Example configuration file (conffile) |
| `/usr/share/man/man8/maglevd.8.gz` | Man page |
| `/usr/share/man/man1/maglevc.1.gz` | Man page |
## Running
After installing, the unit is enabled but not started automatically:
```sh
# edit /etc/maglev/maglev.yaml, then:
systemctl start maglevd
# edit /etc/vpp-maglev/maglev.yaml, then:
systemctl enable --now vpp-maglevd
```
## Run
Or run the server and client by hand:
```sh
maglevd --config /etc/maglev/maglev.yaml --grpc-addr :9090
maglevd --config /etc/vpp-maglev/maglev.yaml --grpc-addr :9090
maglevd --version # print version and exit
maglevc --server localhost:9090 # interactive shell
maglevc show backend nginx0-ams # one-shot
maglevc show frontends # one-shot
maglevc -color=false show backends # one-shot, no ANSI color
maglevc set backend nginx0-ams pause
```
@@ -58,35 +41,7 @@ maglevc set backend nginx0-ams pause
Send `SIGHUP` to `maglevd` to reload config without restarting.
`maglevd` requires `CAP_NET_RAW` for ICMP health checks.
## Minimal config
```yaml
maglev:
healthchecks:
http:
type: http
port: 80
params:
path: /healthz
interval: 2s
timeout: 3s
backends:
web0: {address: 192.0.2.10, healthcheck: http}
web1: {address: 192.0.2.11, healthcheck: http}
frontends:
web:
address: 192.0.2.1
protocol: tcp
port: 80
pools:
- name: primary
backends:
web0: {}
web1: {}
```
Check out a minimal configuration file in [[debian/maglev.yaml](debian/maglev.yaml)].
See [docs/user-guide.md](docs/user-guide.md) for flags, signals, and `maglevc` usage.
See [docs/config-guide.md](docs/config-guide.md) for the full configuration reference.
See [docs/healthchecks.md](docs/healthchecks.md) for health state machine details.
@@ -95,5 +50,5 @@ See [docs/healthchecks.md](docs/healthchecks.md) for health state machine detail
```sh
docker build -t maglevd .
docker run --cap-add NET_RAW -v /etc/maglev:/etc/maglev maglevd
docker run --cap-add NET_RAW -v /etc/vpp-maglev:/etc/vpp-maglev maglevd
```