Unicaster

UDP Unicasting Server Node Using a Custom Unicaster Module with Redis

The module retrieves the list of Kubernetes pods to get their IP addresses for sending unicast messages. It is intended to run inside a pod that has access to the Kubernetes service account credentials located at /var/run/secrets/kubernetes.io/serviceaccount. The service account must also be bound to an RBAC role with the necessary permissions to list pods.

Build

To build a module use:

make

to clean:

make clean

See all available targets in Makefile (install/uninstall/reload/run etc.).

Usage

Environment variables available:

• REDIS_BROADCAST_NAME (default is "imq-broker")
• REDIS_BROADCAST_PORT (default is 63000)
• REDIS_BROADCAST_INTERVAL (in seconds, default is 1 second)
• REDIS_BROADCAST_TLS (unset by default, see "TLS" below)
• SELECTED_INTERFACES="10,192.168,172.20" (comma-separated IP patters to match when binding to interfaces)

Either configure through redis.conf or by launching the server with --loadmodule option, like:

redis-server --loadmodule /path/to/unicaster.so

If you need to log messages and errors from module, enable by:

redis-server --loadmodule /path/to/unicaster.so --loglevel verbose

Message format on redis running is:

[REDIS_BROADCAST_NAME]  [REDIS_GUID]    [STATUS]    [REDIS_INTERFACE_HOST]:[REDIS_PORT]   <REDIS_BROADCAST_INTERVAL>  <TRANSPORT>

Where STATUS could be one of "up" or "down", and REDIS_BROADCAST_INTERVAL and TRANSPORT only present if STATUS is "up". TRANSPORT is "tls" when the announced port is the TLS listener and "plain" when it is not — see "TLS" below, e.g:

imq-broker      2cc7c345-3569-44bb-b57a-b72d729d7012    up      127.0.0.1:6380  1   plain
imq-broker      2cc7c345-3569-44bb-b57a-b72d729d7012    up      127.0.0.1:6380  1   plain
imq-broker      2cc7c345-3569-44bb-b57a-b72d729d7012    down    127.0.0.1:6380

The fields are positional and only ever appended to, so a reader that splits on tabs and takes the first five sees exactly what it saw before this field existed.

TLS

The announced port is the one the server is actually listening on. Redis serves TLS by setting port 0 and tls-port <n>, so a TLS broker used to announce <ip>:0 — an address nothing can connect to, and one @imqueue's UDP listener discards as malformed. Such a fleet discovered no broker at all, with nothing in any log to say why: the announcement went out, it was just useless. The module now announces tls-port in that case, and marks the datagram tls.

When both listeners are up, the plaintext port is announced. That is what an existing fleet is already connecting to, and upgrading this module must not move it onto a transport its clients are not configured for. Set REDIS_BROADCAST_TLS=1 to announce the TLS port instead; 0 pins plaintext.

If the requested listener is not up — REDIS_BROADCAST_TLS=1 with no tls-port, or a server listening nowhere — nothing is announced, and the reason is logged at warning. Announcing a port that refuses connections, or quietly downgrading a fleet that asked for TLS, are both worse than being missing.

The marker describes the announced port and nothing else. It carries no certificate and configures no client: services still supply their own TLS options (IMQ_REDIS_TLS* in @imqueue/core).