Implementing Lua in HAProxy

Essential Background and Use Cases

HAProxy, a highly performant and widely adopted load balancer and proxy server, extends its capabilities significantly by embedding Lua scripting. Lua integration allows advanced, customizable logic to handle complex routing decisions, traffic management, security enhancements, and request/response manipulation. This blog post provides a comprehensive overview of the essential background knowledge required for implementing Lua in HAProxy across various scenarios.

1. Understanding Lua Basics

Before diving into implementation, a solid grasp of Lua programming is necessary:

• Syntax and Data Types: Lua is dynamically typed with basic data types like numbers, strings, booleans, tables, and functions.
• Control Structures: Familiarity with loops (for, while), conditional statements (if, else), and error handling (pcall, xpcall) is essential.
• Functions and Closures: Understanding how to define and use functions, including anonymous functions and closures, significantly aids script writing.

2. HAProxy Lua Integration Points

Lua scripts in HAProxy operate at various hook points:

• Actions: Execute scripts within http-request, http-response, or tcp-request contexts.
• Converters: Custom Lua functions that transform data, often used within ACLs or configuration logic.
• Fetches: Lua functions returning values from request or response processing, accessible to HAProxy configurations.
• Services: Implement backend services entirely through Lua scripts, offering custom protocol handling and responses.

3. HAProxy Lua API Essentials

To effectively write Lua scripts, familiarity with HAProxy’s Lua API is required:

• Core classes and methods:
  • core class (e.g., core.log(), core.Debug())
  • txn class to access and modify HTTP transactions (txn:get_var(), txn:set_var(), txn.http:req_get_headers())
  • http class for header manipulations (http.req, http.res)
• Socket and TCP handling: Methods to manage low-level socket operations directly from Lua scripts, useful for custom TCP protocol implementations.

4. Common Use Cases of Lua in HAProxy

• Dynamic Routing and Load Balancing:
  • Route requests based on custom criteria like headers, payloads, or external data sources.
  • Implement custom algorithms beyond HAProxy’s built-in options.
• Security and Access Control:
  • Inspect and block requests based on advanced patterns (rate limiting, request fingerprinting).
  • Dynamically manage ACLs and block lists.
• HTTP Manipulation and Transformation:
  • Rewrite request and response headers or bodies dynamically.
  • Implement custom authentication or token verification mechanisms.
• Real-time Metrics and Logging:
  • Capture and export real-time metrics or logs to external monitoring tools like Prometheus, Grafana, or Elastic Stack.
  • Provide custom telemetry tailored specifically for operational needs.

5. Practical Example: Basic Lua Script for HTTP Header Inspection

Here’s a concise example of a Lua script inspecting HTTP headers and taking action based on conditions:

core.register_action("inspect_headers", { "http-req" }, function(txn)
    local user_agent = txn.sf:req_hdr("User-Agent")
    if user_agent and user_agent:match("curl") then
        core.log(core.info, "Curl request detected")
        txn:set_var("txn.block", true)
    end
end)

And integrating it in HAProxy configuration:

frontend http_in
    bind *:80
    http-request lua.inspect_headers
    http-request deny if { var(txn.block) -m bool }

6. Performance Considerations

When implementing Lua scripts in HAProxy, performance is crucial:

• Keep Lua scripts concise and optimized.
• Avoid heavy computations or blocking I/O within Lua.
• Utilize built-in HAProxy features where possible, limiting Lua to scenarios where native functionalities are insufficient.

Conclusion

Embedding Lua scripts within HAProxy significantly enhances its flexibility, allowing tailored solutions to complex routing and security problems. However, a clear understanding of Lua programming, HAProxy integration points, and thoughtful script optimization is essential to effectively leverage this powerful capability.

By mastering the fundamentals outlined in this post, you’ll be well-prepared to use Lua scripting to extend HAProxy’s capabilities for robust and customizable traffic management.