Introducing the OpenProvider Diameter Front
Moving a Diameter AAA platform onto Kubernetes looks simple on paper. You put your Diameter servers in a StatefulSet, add a Service in front of them, and let Kubernetes spread the load. It works right up to the first EAP-AKA authentication, and then it stops working.
This article explains why that happens, what we built to fix it, and how it performed under load.
The problem: Diameter sessions have stated, and load balancers don’t know it
A single EAP-AKA authentication over the SWm interface is not one request. It is a conversation of several rounds:
- The ePDG snds a Diameter-EAP-Request (DER).
- The AAA server fetches authentication vectors from the HSS (MAR/MAA) and answers with an EAP challenge.
- The ePDG sends a second DER carrying the subscriber’s response.
- The AAA server verifies it, registers with the HSS (SAR/SAA) and answers with success.
Steps 2 and 4 must happen on the same AAA server. The challenge state lives in that server’s memory. It cannot migrate, and no other server can verify a response to a challenge it never issued.
Where that state lives between the two rounds is not defined by the standards. RFC 4072 and 3GPP TS 29.273 specify what is exchanged, not where the server keeps it in the meantime. Our AAA keeps it in memory, as most AAA servers do. The state lives for a fraction of a second, and losing it costs one re-authentication, nothing more. Keeping it in a shared database would let any server continue any session, but every round would then pay for a write and a consistent read across replicas. In-memory state is the fast design, and session-aware routing is what makes it possible in a horizontally scaled cluster.
A Kubernetes Service, MetalLB, or any other Layer 4 load balancer works with TCP connections. It has no idea what a Session-Id is. Diameter peers also keep long-lived connections and multiplex thousands of sessions over each one, so balancing by connection either sends everything to one backend or, if you force it to spread, breaks multi-round authentication.
Two more requirements make the picture complete:
- Topology hiding. External peers such as ePDGs, PGWs and HSSs should see one Diameter node, not a changing pool of pods with names that come and go on every restart.
- Safe routing. A request must never reach the wrong peer just because that peer is in the same realm and advertises the same application.
Commercial Diameter Routing Agents solve this, but they are large, separate products. When we looked for a lightweight open-source component that does this inside Kubernetes, next to a freeDiameter-based AAA, we did not find one. So we built it.
What the Diameter Front is
The Diameter Front is a single, externally visible Diameter node that sits in front of a pool of AAA backends. External peers connect only to the front. The front relays every message to the correct backend and returns the answer as if it had answered itself.
It is built on freeDiameter as a dedicated routing extension. The front only relays and never answers requests itself. It carries no application logic, no scripting runtime and no LDAP client, which keeps it small and keeps its attack surface small.
How it works
Session stickiness
Every message is routed by its Session-Id. The first message of a new session is assigned a backend, and every later message of that session goes to the same backend for as long as that backend is available. This is what makes multi-round EAP work.
The mapping is removed when the session ends with a Session-Termination-Request. Sessions that never end cleanly are cleaned up after a configurable timeout, so the table cannot grow forever.
Least-sessions balancing
A new session goes to the available backend with the fewest active sessions. Ties are broken at random. This comes almost for free from the stickiness table, and it suits scaling out: a newly added backend starts with zero sessions, so it naturally attracts new traffic until it catches up.
An explicit backend set
The backend pool is defined explicitly. Only peers that match it can ever be chosen as a backend, and everything else is refused. This is a safety property, not a convenience. Without it, a request could be routed to another client that happens to share the realm and the application. If no backend is available, the request fails cleanly with DIAMETER_UNABLE_TO_DELIVER instead of going somewhere it should not.
In practice, the front keeps two separate lists:
Allowed clients | who may connect to the front |
Backend pool | who may be routed to |
Keeping them separate means one client can never receive another client’s request.
Topology hiding
On requests, the front removes Destination-Host, so stickiness alone decides which backend gets the message. On answers, it rewrites Origin-Host and Origin-Realm to its own identity. To the outside world there is one AAA node, whatever happens behind it.
Traffic in both directions
The front does not only carry requests coming in from the network. During authentication, the AAA backends themselves send requests to the HSS: a Multimedia-Auth-Request (MAR) to fetch authentication vectors, and a Server-Assignment-Request (SAR) to register the subscriber. These also go through the front, and their answers come back through it to the backend that asked.
As a result, the HSS has exactly one peer on the AAA side: the front. It does not need to know how many backends there are, and nothing changes on the HSS when the pool grows, shrinks or a backend restarts with a new address. The same applies to every other peer the backends may need to reach.
Configurable application advertisement
When a peer connects, the front announces which Diameter applications it supports in its Capabilities-Exchange-Answer. Some peers require this to match exactly what they expect. The front supports two modes:
- Relay (wildcard). The default. The front advertises the Relay application and accepts any application, as a standard Diameter relay agent does. This is the simplest choice when the peers accept a relay.
- Specific applications. The front advertises only the applications you list, for example SWm, SWx and S6b, and not the Relay wildcard. Peers that insist on seeing their own application in the capabilities exchange will then accept the front as if it were the AAA server itself.
This changes only what the front announces. Routing, stickiness and the backend pool work the same way in both modes.
What the front deliberately does not do
Not included | Why |
Application handlers | The front relays and never answers. Loading them would make it serve requests locally instead of forwarding them. |
A second load balancer | Session stickiness is the load balancer. Two would fight each other. |
A separate topology-hiding module | Topology hiding is built into the extension. |
PHP, LDAP, application code | A relay needs none of them, and every package left out is one less thing for a security scan to flag. |
Running on Kubernetes
The front is delivered as a Helm chart and is designed for hardened Kubernetes platforms from the start:
- Read-only root file system. The full configuration is generated at container start from Helm values. Nothing is patched in place, and the generated configuration is printed to the log so you can always see what the process was actually given.
- TCP and SCTP. SCTP is the transport that RFC 6733 and 3GPP prefer, so it is on by default. Both protocols share the Diameter port and are exposed on the same LoadBalancer address.
- External address through MetalLB, with externalTrafficPolicy: Local so peers’ real source addresses are preserved.
- NetworkPolicy included. The chart ships its own policy with ingress from clients and egress only to the backends and the configured peers.
- Stable peer addresses. Each backend is reached through its own ClusterIP Service, so a backend that restarts and gets a new pod IP is still reachable at the same address.
Requests and limits on every container, as hardened platforms require.
Configuration
One step is easy to miss: freeDiameter rejects a connection from a peer it does not know. The front is registered as a peer on the backend side as well, so the connection between them comes up in both directions.
High availability
The session map is held in memory on each front and is not shared between fronts. EAP state cannot move between AAA servers anyway, so there is no mid-session failover to build.
A second front runs alongside the first, with its own address, and can be used in two ways:
- As a standby. Peers send traffic to the first front and switch to the second only if the first becomes unavailable.
- As another peer’s primary. If the operator connects to the AAA through two Diameter Routing Agents (DRAs), each DRA can use a different front as its first choice and the other as its backup, so both fronts carry traffic at the same time.
What matters is that a single peer, whether a DRA, an ePDG, a PGW or an HSS, never load-balances across the front nodes. Each front knows only the sessions that passed through it. If the second round of an authentication reached the other front, that front would treat it as a new session, could send it to a different AAA server, and the authentication would fail. A peer should treat the fronts as primary and backup, never as a pool.
Results
We tested the front with traffic generators simulating ePDG, PGW and HSS, all connected to a single front in front of two AAA backends backed by a three-node Cassandra cluster.
Correctness. Verified from packet captures:
- Full EAP-AKA over SWm from start to finish: DER, MAR/MAA, challenge, second DER, SAR/SAA, success, with the HSS traffic relayed through the front in both directions.
- S6b authorization from the PGW after successful authentication.
- Stickiness 10/10. Both rounds of every subscriber’s authentication were answered by the same backend.
- Even distribution between backends.
Throughput.
Sustained load | 8,500–10,000 Diameter transactions per second |
Equivalent | roughly 850–1,000 complete EAP-AKA authentications per second (8–10 messages each) |
Front CPU | ~1.1 cores |
Each AAA backend CPU | ~1.1 cores |
Cassandra CPU, per node | ~1 core |
CPU throttling | zero, on the front and on both backends |
Duration | 16 hours of continuous load, stable memory, no restarts |
The front itself had no impact on performance: it relayed the full load without becoming a bottleneck at any point in the test.
Lessons from the field
A few things we learned the hard way, which may save time for anyone running Diameter on Kubernetes:
- freeDiameter resolves peer addresses only once, at startup. A pod that restarts gets a new IP, and its peers will keep calling the old one forever. Give every peer a stable address, such as a ClusterIP Service per pod.
- Don’t pin a single VIP to a node. With externalTrafficPolicy: Local, MetalLB announces an address only from a node that has a ready local pod. If you pin the address to a different node, nobody announces it, and from outside it looks exactly like a firewall drop.
- No syslog in a read-only container. freeDiameter’s -s flag sends logs to syslog, and a hardened container usually has no syslog daemon. The messages that would explain the failure simply disappear.
- Message dumps don’t belong in production. Full message dumping at thousands of requests per second blocks worker threads on writes to stdout. The process stays alive and the connection stays healthy, but nothing is answered.
- SCTP needs its own firewall rule. It is IP protocol 132, not TCP, and every misconfiguration shows up as “the peer just doesn’t connect”.
Summary
The OpenProvider Diameter Front gives a freeDiameter-based AAA what a Kubernetes Service cannot: session-aware routing that keeps multi-round EAP on one server, balancing that scales out naturally, strict control over where requests may go, and a single, stable Diameter identity towards the network, advertising either the Relay wildcard or exactly the applications your peers expect. It is small, built for hardened platforms, and has carried 8,500–10,000 transactions per second for 16 hours using a fraction of its resources.
The Diameter Front is part of the OpenProvider AAA platform. Contact us to learn more.