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

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

Browse Source 
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:
Pim van Pelt
2026-04-11 16:42:11 +02:00
parent d612086a5f
commit 58391f5463
26 changed files with 1969 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
docs/config-guide.md
View File

@@ -11,7 +11,7 @@ in two stages:
ensuring that every backend referenced by a frontend exists, that address families are
consistent within a frontend, and that IP source addresses are the correct family.
If you want to get started quickly, take a look at the [example config](#example).
If you want to get started quickly, take a look at the [[example config](../debian/mavleg.yaml)].
## Basic structure
@@ -277,109 +277,7 @@ frontends:
---
## Example
For a detailed description of the health state machine, probe intervals, and all transition events,
see [[healthchecks.md](healthchecks.md)]. For a user guide on how to use the maglev daemon and client,
see the [[user-guide.md](user-guide.md)].
A complete configuration tying all sections together:
```yaml
maglev:
healthchecker:
transition-history: 5
netns: dataplane
healthchecks:
nginx:
type: http
port: 80
params:
path: /healthz
host: nginx.example.com
response-code: "200"
interval: 2s
fast-interval: 500ms
down-interval: 30s
timeout: 3s
rise: 2
fall: 3
dovecot:
type: tcp
port: 993
params:
ssl: true
server-name: imaps.example.com
interval: 5s
fast-interval: 1s
down-interval: 30s
timeout: 3s
rise: 2
fall: 3
ping6:
type: icmp
probe-ipv6-src: 2001:db8:probe::1
interval: 2s
timeout: 1s
backends:
nginx0-ams:
address: 198.51.100.10
healthcheck: nginx
nginx0-lon:
address: 198.51.100.11
healthcheck: nginx
nginx0-fra:
address: 198.51.100.12
healthcheck: nginx
maildrop0-ams:
address: 2001:db8:1::10
healthcheck: dovecot
maildrop0-lon:
address: 2001:db8:1::11
healthcheck: dovecot
frontends:
nginx-http:
description: "HTTP VIP with fallback"
address: 198.51.100.1
protocol: tcp
port: 80
pools:
- name: primary
backends:
nginx0-ams: { weight: 10 }
nginx0-lon: {}
- name: fallback
backends:
nginx0-fra: {}
nginx-https:
description: "HTTPS VIP — same backends, different port"
address: 198.51.100.1
protocol: tcp
port: 443
pools:
- name: primary
backends:
nginx0-ams: { weight: 10 }
nginx0-lon: {}
- name: fallback
backends:
nginx0-fra: {}
maildrop-imaps:
description: "IMAPS VIP"
address: 2001:db8::1
protocol: tcp
port: 993
pools:
- name: primary
backends:
maildrop0-ams: {}
maildrop0-lon: {}
```
---
For a detailed description of the health state machine, probe intervals, and all
transition events, see [healthchecks.md](healthchecks.md).

19
docs/maglevd.8
View File

@@ -6,6 +6,7 @@ maglevd \- Maglev health\-checker daemon
[\fB\-config\fR \fIfile\fR]
[\fB\-grpc\-addr\fR \fIaddr\fR]
[\fB\-log\-level\fR \fIlevel\fR]
[\fB\-reflection\fR[=\fIbool\fR]]
[\fB\-version\fR]
.SH DESCRIPTION
.B maglevd
@@ -32,7 +33,7 @@ parentheses); the flag takes precedence.
.TP
.BI \-config " file"
Path to the YAML configuration file.
.RI "(default: " /etc/maglev/maglev.conf "; env: " MAGLEV_CONFIG )
.RI "(default: " /etc/vpp-maglev/maglev.yaml "; env: " MAGLEV_CONFIG )
.TP
.BI \-grpc\-addr " addr"
TCP address on which the gRPC server listens.
@@ -47,6 +48,16 @@ or
.BR error .
.RI "(default: " info "; env: " MAGLEV_LOG_LEVEL )
.TP
.B \-reflection
Enable gRPC server reflection so that clients such as
.BR grpcurl (1)
can introspect the API without access to the
.I .proto
file.
Enabled by default; pass
.B \-reflection=false
to disable.
.TP
.B \-version
Print version, commit hash, and build date, then exit.
.SH SIGNALS
@@ -60,10 +71,10 @@ backend workers are left running.
Gracefully shut down: drain active gRPC streams, then exit.
.SH FILES
.TP
.I /etc/maglev/maglev.conf
.I /etc/vpp-maglev/maglev.yaml
Default configuration file (YAML).
.TP
.I /etc/default/maglev
.I /etc/default/vpp-maglev
Environment file sourced by the systemd unit before starting
.BR maglevd .
.SH CONFIGURATION
@@ -77,7 +88,7 @@ and
.BR frontends .
.PP
See the example at
.I /etc/maglev/maglev.conf
.I /etc/vpp-maglev/maglev.yaml
and the full reference in the project documentation.
.SH SEE ALSO
.BR maglevc (1)

36
docs/user-guide.md
View File

@@ -10,9 +10,11 @@ inspection and control.
| Flag | Environment variable | Default | Description |
|---|---|---|---|
| `--config` | `MAGLEV_CONFIG` | `/etc/maglev/maglev.yaml` | Path to the YAML configuration file. |
| `--config` | `MAGLEV_CONFIG` | `/etc/vpp-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`. |
| `--check` | — | — | Read and validate the config file, then exit. Exits 0 if the config is valid, 1 on YAML parse error, 2 on semantic error. |
| `--reflection` | — | `true` | Enable gRPC server reflection. Allows `grpcurl` to introspect the API without the `.proto` file. Set to `false` to disable. |
| `--version` | — | — | Print version, commit hash, and build date, then exit. |
Flags take precedence over environment variables. Both are optional; defaults
@@ -22,7 +24,7 @@ are used for anything not set.
| 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. |
| `SIGHUP` | Reload the configuration file. The file is checked before applying; if there is a parse or semantic error the reload is aborted and the error is logged (the daemon continues running with its current config). 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
@@ -83,6 +85,36 @@ 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.
set frontend <name> pool <pool> backend <name> weight <0-100>
Set the weight of a backend within a pool. Weight 0 keeps
the backend in the pool but assigns it no traffic.
Takes effect immediately without reloading configuration.
set backend <name> disable Stop probing entirely and remove the backend from rotation.
The backend remains visible (state: removed) and can be
re-enabled without reloading configuration.
set backend <name> enable Re-enable a disabled backend. A fresh probe goroutine is
started and the backend re-enters unknown state.
watch events Stream all events (log, backend transitions, frontend)
[num <n>] Stop after receiving n events.
[log [level <level>]] Include log events. level is debug|info|warn|error
(default: info). Omitting log/backend/frontend enables all.
[backend] Include backend transition events.
[frontend] Include frontend events (reserved for future use).
Each event is printed as compact JSON on its own line.
Press any key or Ctrl-C to stop. Examples:
watch events
watch events num 20
watch events log level debug
watch events backend num 100
watch events log level debug backend
config check Ask maglevd to read and validate its current config file.
Prints "config ok" on success, or the error (parse or
semantic) returned by the daemon.
quit / exit Leave the interactive shell.
```