Skip to main content
XenonStack

Cloud Native Applications

XenonStack Blog Katran L4 Load Balancer: XDP Architecture Explained

and | Published | Updated

Katran L4 Load Balancer: XDP Architecture Explained
12:39

Key takeaway

  • Katran is Meta's open-source layer 4 load balancer. See how XDP, Maglev hashing and DSR work, what it needs to run, and when to use L7 proxies instead.

Katran is an open-source layer 4 load balancer from Meta. According to its Katran repository on GitHub, it is "a C++ library and BPF program to build high-performance layer 4 load balancing forwarding plane". It decides which backend receives each TCP or UDP flow by looking only at addresses, ports and protocol, and it does this inside the Linux kernel using XDP, so packets are handled before the normal network stack sees them.

This guide is for platform and network architects who need to decide whether a kernel-level L4 forwarding plane belongs in their stack. It explains how Katran works, what running it involves, where an L7 proxy is still needed, and how to govern changes to it. For the kernel technology underneath, see our guide to eBPF for secure managed services.

What is Katran and where does it fit?

Meta describes Katran in its Meta engineering post of 22 May 2018 as the forwarding plane behind its network load balancer, deployed on backend servers in its points of presence (PoPs). The project is published as facebookincubator/katran under the GPL-2.0 licence. It is a building block, not a packaged appliance: you embed the C++ library in your own control plane, or adapt the examples in the repository.

In a typical layered design, an L4 tier spreads flows across a fleet of L7 proxies or application servers, and the L7 tier handles TLS, HTTP routing and content rules. Katran occupies the first tier only.

How does Katran forward packets?

Katran combines a small set of well-defined techniques. The table below lists each one and what it does, as stated in the repository README and in Meta's engineering post.

Two columns: layer 4 tier with XDP program, Maglev hashing, IP-in-IP forwarding and connection table; layer 7 tier with TLS termination, HTTP routing, content rules and application servers.
TechniqueWhat it doesWhy it matters
XDPRuns a BPF program on every incoming packet, in driver mode as soon as the network card receives it; a slower generic mode also existsAvoids the cost of the full kernel network stack
Modified Maglev hashingPicks a backend by consistent hashing and supports unequal backend weightsSeparate L4 nodes choose the same backend without sharing state
IP-in-IP encapsulationForwards packets to the next tier with an outer header whose source address varies by flowSpreads flows across receive queues (RSS) while keeping each flow on one path
Direct service response (DSR)Katran works only in DSR mode, so return traffic does not pass back through itThe load balancer handles the inbound direction only
Connection trackingA fixed-size table with LRU evictionKeeps existing flows on their backend when the backend set changes
Per-CPU, lockless designUses per-CPU BPF maps; Meta says throughput scales linearly with the number of NIC receive queuesCapacity grows with hardware queues rather than lock contention

Layer 4 or layer 7: which do you need?

Layer 4 balancing is a routing decision made on the connection, so it cannot read HTTP headers, cookies or terminate TLS. Layer 7 proxies can, at a higher processing cost per request. Most large estates use both.

RequirementLayer 4 (Katran type)Layer 7 proxy
Route on IP, port and protocolFitsFits
Route on URL, header or cookieDoes not fitFits
TLS terminationDoes not fit; Katran does not terminate TLSFits
Very high packet rates with simple rulesFits wellCosts more CPU per request
UDP and non-HTTP servicesFitsDepends on the proxy
Operating effortYou own a kernel-level data plane and control planeMature products with ready management tools

See also our guides to cloud versus edge placement and Kubernetes architecture components, where service load balancing is a separate concern from the node-level L4 tier discussed here.

What does running Katran involve?

The repository lists a recent Linux kernel (5.6 or later) and a recent clang (6.0 or later); builds were tested on Ubuntu 20.04, and other distributions need extra libraries such as folly, glog and gflags. The USAGE.md guide describes the control plane steps:

  • Create and attach: populate a KatranConfig, create a KatranLb instance, then load and attach the BPF programs. The kernel verifier can reject a program, in which case the library throws.
  • Standalone or shared mode: attach directly to an interface, or register the program in a shared root XDP program.
  • Define services: a virtual IP is identified by address, port and protocol, and backends ("reals") carry a weight. Setting a weight to 0 or removing a real drains it, although existing connections stay on it unless the VIP uses the LRU bypass flag.
  • Size the tables: the consistent-hash ring size must be a prime number (default 65537), and the maximum VIPs and reals must match compile-time constants.
  • Health checking: health-check traffic is marked with a socket mark that Katran maps to a chosen real.

What are the strengths and limits?

AreaStrengthLimit or caution
Performance designXDP, per-CPU maps and no busy loops on the receive path, per MetaMeta gives no portable benchmark; measure on your own hardware and traffic
Statelessness across nodesConsistent hashing lets several L4 nodes agree on a backendChanging the backend set can still disturb flows that are not in the connection table
Licence and costOpen source under GPL-2.0, no licence feeCheck the GPL-2.0 terms with your legal team before embedding it in a product you distribute
ScopeDoes one job at layer 4DSR only; no TLS or HTTP-level routing; the QUIC VIP flag is described in USAGE.md as not fully stable
OperationsLibrary you can adapt to your own control planeThe repository shows no tagged release; you own build, upgrade and kernel compatibility

How should an enterprise decide and adopt it?

  1. Confirm the need: measure whether your current load balancer is CPU-bound on packet rate. If it is not, a managed cloud load balancer is usually the lower-effort choice.
  2. Check the platform: confirm kernel version, NIC driver support for XDP driver mode, and your security review of loading BPF programs. Our guide to cloud-native security covers the surrounding controls.
  3. Prove it on a small VIP: run one low-risk service, compare against your baseline, and test backend drain and failure.
  4. Build the control plane: decide who changes VIPs, weights and health checks, and how changes are reviewed and rolled back.
  5. Keep the L7 tier: leave TLS and HTTP routing with proxies built for them.

How do you govern changes to a load balancer?

A load balancer change is a production decision: a wrong weight or a drained pool can take a service down. As teams let automation, and increasingly AI agents, propose these changes, the useful questions are who may change which VIP, what evidence supports the change, and how it is reversed. ElixirData Context OS keeps governed context, versioned policy and decision traces in one decision layer above AI agents, and ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control.

Our own view is that the data plane should stay simple and fast, while the decisions about it stay reviewable.

To map one traffic or load-balancer change your automation or agents should make, and the policy and context it depends on, book a Context Workshop. See what happens in the workshop.

Frequently asked questions

What is Katran?

Katran is an open-source layer 4 load balancer from Meta. Its GitHub README describes it as a C++ library and BPF program for building a high-performance layer 4 load balancing forwarding plane.

How does Katran differ from an L7 load balancer?

Katran decides on address, port and protocol only, so it cannot route on URLs, headers or cookies or terminate TLS. An L7 proxy can, at a higher processing cost per request.

Does Katran use XDP and eBPF?

Yes. Meta says it is built on XDP and the eBPF virtual machine, running a BPF program on every incoming packet, in driver mode as soon as the network card receives it.

What does Katran need to run?

The repository lists Linux kernel 5.6 or later and clang 6.0 or later, tested on Ubuntu 20.04. Confirm the current requirements on the GitHub page before you plan a deployment.

Does Katran work with return traffic?

Katran works only in direct service response (DSR) mode, so return traffic from backends does not pass back through it.

Is Katran the right choice for every team?

No. It is a library you integrate and operate yourself. If a managed cloud load balancer meets your packet rate and routing needs, it is usually the lower-effort option.

Katran – Advancing Layer 4 Operations

Connect with our experts to explore how Katran empowers industries and departments with Agentic Workflows and Decision Intelligence. Leverage Katran’s capabilities to optimize IT support and operations, driving automation, efficiency, and responsiveness for decision-centric organizations.

Follow XenonStack on LinkedIn: XenonStack on LinkedIn for new guides on agentic AI, data and platform engineering.

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in solving your challenges with the XenonStack team?
Get Started

Tell us about you and your priorities so we can prepare the right conversation. It takes about 2 minutes.

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Continue