Implement Plugin System with Built-in Plugins and Comprehensive Examples

[byjg]

Summary

This PR implements a complete plugin system for EasyHAProxy, including four built-in security plugins, comprehensive test coverage, and extensive documentation with runnable examples across all deployment methods.

---

Major Features

🔌 Plugin System Architecture

Plugin Types:

• PluginType.DOMAIN - Execute once per domain/host
• PluginType.GLOBAL - Execute once per discovery cycle

Configuration Sources (in order of precedence):

• Docker: Container labels > YAML config > Environment variables
• Kubernetes: Ingress annotations > YAML config > Environment variables
• Swarm: Service labels > YAML config > Environment variables
• Static: Per-domain config > Global plugins > Environment variables

Plugin Lifecycle:

1. Discovery and loading from src/plugins/builtin/ and custom paths
2. Validation of plugin configuration
3. Execution with context (domain info, SSL settings, etc.)
4. HAProxy configuration injection

---

🛡️ Built-in Plugins

1. JWT Validator Plugin

File: src/plugins/builtin/jwt_validator.py

Features:

• Validates JWT tokens using RS256 algorithm
• Supports issuer and audience validation
• Configurable public key path
• Validates token signature and expiration
• Returns meaningful HTTP errors for validation failures

Configuration Example:

plugins:
  - jwt_validator
plugin_config:
  jwt_validator:
    algorithm: RS256
    issuer: https://auth.example.com/
    audience: https://api.example.com
    pubkey_path: /etc/haproxy/jwt_keys/api_pubkey.pem

2. IP Whitelist Plugin

File: src/plugins/builtin/ip_whitelist.py

Features:

• Restricts access to specific IP addresses or CIDR ranges
• Supports multiple IPs (comma-separated)
• Configurable HTTP status code (403 or 404)
• Ideal for admin panels and internal tools

Configuration Example:

plugins:
  - ip_whitelist
plugin_config:
  ip_whitelist:
    allowed_ips: 192.168.0.0/16,10.0.0.0/8
    status_code: 403

3. Deny Pages Plugin

File: src/plugins/builtin/deny_pages.py

Features:

• Blocks access to specific URL paths
• Supports path prefix matching
• Configurable HTTP status code
• Protects sensitive endpoints like /admin, /.env, /wp-admin

Configuration Example:

plugins:
  - deny_pages
plugin_config:
  deny_pages:
    paths: [/admin, /.env, /config]
    status_code: 404

4. Cloudflare Plugin

File: src/plugins/builtin/cloudflare.py

Features:

• Restores original visitor IP from Cloudflare headers
• Validates requests come from Cloudflare IPs
• Sets X-Forwarded-For header with real visitor IP
• Supports custom Cloudflare IP list path

Configuration Example:

plugins:
  - cloudflare
plugin_config:
  cloudflare:
    ip_list_path: /etc/haproxy/cloudflare_ips.lst

---

🧪 Testing

Added comprehensive plugin test suite with 34 new tests:

• Plugin discovery and loading
• Configuration validation
• HAProxy config generation
• Global vs domain plugin execution
• Plugin enabled/disabled logic
• Critical bug fix: Plugins now correctly skip execution when enabled_list=None

Test Results:

pytest -c src/tests -v
# 80 tests passed (including 34 plugin-specific tests)

---

📁 File Structure

Core Plugin System

• src/plugins/__init__.py - Plugin base classes and discovery logic
• src/plugins/builtin/jwt_validator.py - JWT validation plugin
• src/plugins/builtin/ip_whitelist.py - IP restriction plugin
• src/plugins/builtin/deny_pages.py - Path blocking plugin
• src/plugins/builtin/cloudflare.py - IP restoration plugin
• src/processor/__init__.py - Modified to integrate plugin system
• src/easymapping/__init__.py - Modified to support plugin configuration
• src/templates/haproxy.cfg.j2 - Modified to inject plugin configurations

Documentation

• docs/plugins.md - Complete plugin system documentation
• docs/plugin-development.md - Guide for creating custom plugins
• examples/docker/README.md - Docker Compose examples guide (165+ lines)
• examples/kubernetes/README.md - Kubernetes ingress examples guide (485+ lines)
• examples/static/README.md - Static configuration guide (437+ lines)
• examples/swarm/README.md - Docker Swarm deployment guide (596+ lines)

---

🚀 Runnable Examples (12 files)

Docker Compose Examples (4 files)

• examples/docker/docker-compose-jwt-validator.yml - JWT token validation with key generation and test commands
• examples/docker/docker-compose-cloudflare.yml - Cloudflare IP restoration with download instructions
• examples/docker/docker-compose-ip-whitelist.yml - IP address restriction with CIDR notation examples
• examples/docker/docker-compose-plugins-combined.yml - Multiple plugins working together

Kubernetes Examples (4 files)

• examples/kubernetes/jwt-validator.yml - Complete JWT setup with ConfigMap, Deployment, Service, and Ingress
• examples/kubernetes/cloudflare.yml - Cloudflare IP restoration with actual IP ranges in ConfigMap
• examples/kubernetes/ip-whitelist.yml - IP whitelist with annotation-based configuration
• examples/kubernetes/plugins-combined.yml - Three-tier security setup (Website, API, Admin)

Docker Swarm Examples (4 files)

• examples/swarm/jwt-validator.yml - JWT validation using Docker configs with creation commands
• examples/swarm/cloudflare.yml - Cloudflare IP restoration using Docker configs
• examples/swarm/ip-whitelist.yml - IP whitelist with service label syntax
• examples/swarm/plugins-combined.yml - Production-ready multi-service stack

Static Configuration Examples (4 files)

• examples/static/conf/config-basic.yml - Minimal configuration without plugins
• examples/static/conf/config-deny-pages.yml - Global plugin with per-domain overrides
• examples/static/conf/config-jwt-validator.yml - JWT validation for multiple APIs
• examples/static/conf/config-certbot.yml - Let's Encrypt/ACME automatic SSL certificates

---

🐛 Bug Fixes

1. Critical: Plugin execution with None enabled_list

Problem: Plugins were executing even when enabled_list=None

Fix: Added proper check to skip plugin execution when no plugins are enabled

Impact: Prevents unnecessary plugin execution and potential errors

2. Double indentation in HAProxy output

Problem: Plugins were adding 4 spaces to HAProxy config lines, and the Jinja2 template was also adding 4 spaces via indent(4, first=True), resulting in 8 spaces total instead of 4.

Fix: Removed indentation from all plugin output. The Jinja2 template now handles all indentation consistently.

Files Modified:

• src/plugins/builtin/jwt_validator.py
• src/plugins/builtin/ip_whitelist.py
• src/plugins/builtin/deny_pages.py
• src/plugins/builtin/cloudflare.py

Before:

haproxy_config = f"""# Deny Pages
    acl denied_path path_beg {paths_str}
    http-request deny deny_status {self.status_code} if denied_path"""

After:

haproxy_config = f"""# Deny Pages
acl denied_path path_beg {paths_str}
http-request deny deny_status {self.status_code} if denied_path"""

---

🎯 Kubernetes Annotation Support

Added full plugin support via Kubernetes Ingress annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    easyhaproxy.plugins: "jwt_validator,deny_pages"
    easyhaproxy.plugin.jwt_validator.algorithm: "RS256"
    easyhaproxy.plugin.jwt_validator.issuer: "https://auth.example.com/"
    easyhaproxy.plugin.deny_pages.paths: "/admin,/.env"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

---

Benefits

1. Extensible Architecture - Easy to add custom plugins for specialized needs
2. Security Hardening - Built-in plugins cover common security requirements (JWT validation, IP whitelisting, path blocking, Cloudflare integration)
3. Multi-Platform Support - Works seamlessly with Docker, Kubernetes, Swarm, and Static modes
4. Production-Ready - Comprehensive test coverage and real-world examples
5. Developer-Friendly - Clear documentation and step-by-step plugin development guide
6. Flexible Configuration - Supports both global and per-domain plugin settings with clear precedence rules

---

Migration Guide

Enabling Plugins

Docker Compose

services:
  app:
    labels:
      easyhaproxy.http.plugins: "jwt_validator,deny_pages"
      easyhaproxy.http.plugin.jwt_validator.algorithm: "RS256"
      easyhaproxy.http.plugin.jwt_validator.issuer: "https://auth.example.com/"
      easyhaproxy.http.plugin.deny_pages.paths: "/admin,/.env"

Kubernetes

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    easyhaproxy.plugins: "jwt_validator"
    easyhaproxy.plugin.jwt_validator.algorithm: "RS256"
    easyhaproxy.plugin.jwt_validator.pubkey_path: "/etc/haproxy/jwt_keys/api.pem"

Static Mode (Global)

plugins:
  enabled:
    - deny_pages
  config:
    deny_pages:
      paths:
        - /admin
        - /.env
      status_code: 404

Static Mode (Per-Domain)

easymapping:
  - port: 443
    ssl: true
    hosts:
      api.local:
        containers:
          - api:8080
        plugins:
          - jwt_validator
        plugin_config:
          jwt_validator:
            algorithm: RS256
            issuer: https://auth.example.com/
            pubkey_path: /etc/haproxy/jwt_keys/api.pem

---

Breaking Changes

None - This is a new feature addition. Existing configurations continue to work without modification.

---

What's Next

Users can now:

• Use built-in security plugins immediately
• Develop custom plugins following the plugin development guide
• Mix and match plugins per domain for flexible security policies
• Deploy with confidence using production-ready examples

[byjg]

Link to Issue #51