badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity

Documentation Refactor

Browse source
This commit is contained in:
Joao Gilberto Magalhaes 2026-02-20 01:05:37 -05:00
parent 3b8818e636
commit a410b34521
47 changed files with 2065 additions and 3911 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/reference/plugins/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "Plugins",
"position": 5
}

80
docs/reference/plugins/cleanup.md Normal file
View file

@ -0,0 +1,80 @@
---
sidebar_position: 6
sidebar_label: "Cleanup"
---
# Cleanup Plugin
**Type:** Global Plugin
**Runs:** Once per discovery cycle
## Overview
The Cleanup plugin performs cleanup tasks during each discovery cycle, such as removing old temporary files.
## Why Use It
Prevents disk space issues by automatically cleaning up temporary files created by EasyHAProxy.
## Configuration Options
| Option | Description | Default |
|----------------------|----------------------------------------------|---------|
| `enabled` | Enable/disable plugin | `true` |
| `max_idle_time` | Maximum age in seconds before deleting files | `300` |
| `cleanup_temp_files` | Enable temp file cleanup | `true` |
## Configuration Examples
### Static YAML Configuration
```yaml
# /etc/easyhaproxy/static/config.yaml
plugins:
enabled: [cleanup]
config:
cleanup:
max_idle_time: 600
cleanup_temp_files: true
```
### Environment Variables
| Environment Variable | Config Key | Type | Default | Description |
|-------------------------------------------------|----------------------|----------|---------|----------------------------------------------|
| `EASYHAPROXY_PLUGINS_ENABLED` | - | string | - | Enable cleanup plugin (value: `cleanup`) |
| `EASYHAPROXY_PLUGIN_CLEANUP_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin |
| `EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME` | `max_idle_time` | integer | `300` | Maximum age in seconds before deleting files |
| `EASYHAPROXY_PLUGIN_CLEANUP_CLEANUP_TEMP_FILES` | `cleanup_temp_files` | boolean | `true` | Enable temp file cleanup |
### Custom Idle Time (1 hour)
```yaml
plugins:
enabled: [cleanup]
config:
cleanup:
enabled: true
max_idle_time: 3600 # 1 hour
```
## How It Works
The cleanup plugin:
- Runs once during each discovery cycle
- Scans temporary directories for old files
- Removes files older than `max_idle_time` seconds
- Helps maintain disk space efficiency
## Important Notes
- This is a **global plugin** - it runs once per discovery cycle, not per domain
- Does not generate HAProxy configuration
- Performs maintenance operations in the background
- Safe to enable in production environments
## Related Documentation
- [Plugin System Overview](../../guides/plugins.md)
- [Environment Variables Reference](../environment-variables.md)
- [Static Configuration Reference](../../getting-started/static.md)

120
docs/reference/plugins/cloudflare.md Normal file
View file

@ -0,0 +1,120 @@
---
sidebar_position: 3
sidebar_label: "Cloudflare"
---
# Cloudflare Plugin
**Type:** Domain Plugin
**Runs:** Once for each discovered domain/host
## Overview
The Cloudflare plugin restores the original visitor IP address when requests come through Cloudflare's CDN. The plugin includes **built-in Cloudflare IP ranges** that are automatically written to the IP list file - no manual configuration required!
## Why Use It
Cloudflare replaces the visitor's IP with its own. This plugin restores the original IP from the `CF-Connecting-IP` header.
## Configuration Options
| Option | Description | Default |
|-------------------|------------------------------------------|---------------------------------------|
| `enabled` | Enable/disable plugin | `true` |
| `use_builtin_ips` | Use built-in Cloudflare IP ranges | `true` |
| `ip_list_path` | Path to Cloudflare IP list | `/etc/easyhaproxy/cloudflare_ips.lst` |
## Configuration Examples
### Docker/Docker Compose (Basic - Uses Built-in IPs)
```yaml
services:
myapp:
labels:
easyhaproxy.http.host: example.com
easyhaproxy.http.plugins: cloudflare
# Built-in Cloudflare IPs are automatically used - no additional configuration needed!
```
### Docker/Docker Compose (Custom IP List)
```yaml
labels:
easyhaproxy.http.plugins: cloudflare
easyhaproxy.http.plugin.cloudflare.use_builtin_ips: false
easyhaproxy.http.plugin.cloudflare.ip_list_path: /custom/path/cf_ips.lst
```
### Kubernetes Annotations
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
easyhaproxy.plugins: "cloudflare"
easyhaproxy.plugin.cloudflare.ip_list_path: "/etc/easyhaproxy/cloudflare_ips.lst"
spec:
rules:
- host: example.com
http:
paths:
- path: /
backend:
service:
name: myapp
port:
number: 80
```
### Static YAML Configuration
```yaml
plugins:
config:
cloudflare:
enabled: true
use_builtin_ips: true # Uses built-in Cloudflare IPs (default)
```
### Environment Variables
| Environment Variable | Config Key | Type | Default | Description |
|-------------------------------------------------|-------------------|----------|---------------------------------------|---------------------------------------|
| `EASYHAPROXY_PLUGIN_CLOUDFLARE_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains |
| `EASYHAPROXY_PLUGIN_CLOUDFLARE_USE_BUILTIN_IPS` | `use_builtin_ips` | boolean | `true` | Use built-in Cloudflare IP ranges |
| `EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH` | `ip_list_path` | string | `/etc/easyhaproxy/cloudflare_ips.lst` | Path to Cloudflare IP list file |
## Generated HAProxy Configuration
```haproxy
# Cloudflare - Restore original visitor IP
acl from_cloudflare src -f /etc/easyhaproxy/cloudflare_ips.lst
http-request set-header X-Forwarded-For %[req.hdr(CF-Connecting-IP)] if from_cloudflare
```
## Built-in Cloudflare IP Ranges
The plugin includes the current Cloudflare IP ranges (22 ranges total):
**IPv4 Ranges (15):**
- 173.245.48.0/20, 103.21.244.0/22, 103.22.200.0/22, 103.31.4.0/22
- 141.101.64.0/18, 108.162.192.0/18, 190.93.240.0/20, 188.114.96.0/20
- 197.234.240.0/22, 198.41.128.0/17, 162.158.0.0/15, 104.16.0.0/13
- 104.24.0.0/14, 172.64.0.0/13, 131.0.72.0/22
**IPv6 Ranges (7):**
- 2400:cb00::/32, 2606:4700::/32, 2803:f800::/32, 2405:b500::/32
- 2405:8100::/32, 2a06:98c0::/29, 2c0f:f248::/32
## Important Notes
- ✅ **No manual configuration required** - Built-in Cloudflare IPs are included!
- The plugin runs once per domain during the discovery cycle
- IP list file is automatically created and updated
## Related Documentation
- [Plugin System Overview](../../guides/plugins.md)
- [Container Labels Reference](../container-labels.md)

123
docs/reference/plugins/deny-pages.md Normal file
View file

@ -0,0 +1,123 @@
---
sidebar_position: 5
sidebar_label: "Deny Pages"
---
# Deny Pages Plugin
**Type:** Domain Plugin
**Runs:** Once for each discovered domain/host
## Overview
The Deny Pages plugin blocks access to specific paths for a domain, returning a configurable HTTP status code.
## Why Use It
Protect admin panels, internal APIs, or debugging endpoints from public access.
## Configuration Options
| Option | Description | Default |
|---------------|----------------------------------------|------------|
| `enabled` | Enable/disable plugin | `true` |
| `paths` | Comma-separated list of paths to block | (required) |
| `status_code` | HTTP status code to return | `403` |
## Configuration Examples
### Docker/Docker Compose (Basic)
```yaml
services:
webapp:
labels:
easyhaproxy.http.host: example.com
easyhaproxy.http.plugins: deny_pages
easyhaproxy.http.plugin.deny_pages.paths: /admin,/private,/debug
easyhaproxy.http.plugin.deny_pages.status_code: 404
```
### WordPress Protection
```yaml
labels:
easyhaproxy.http.host: wordpress.example.com
easyhaproxy.http.plugins: deny_pages
easyhaproxy.http.plugin.deny_pages.paths: /wp-admin,/wp-login.php,/.env
easyhaproxy.http.plugin.deny_pages.status_code: 404
```
### Kubernetes Annotations
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
easyhaproxy.plugins: "deny_pages"
easyhaproxy.plugin.deny_pages.paths: "/admin,/private"
easyhaproxy.plugin.deny_pages.status_code: "403"
spec:
rules:
- host: example.com
http:
paths:
- path: /
backend:
service:
name: webapp
port:
number: 80
```
### Static YAML Configuration
```yaml
containers:
"example.com:80":
ip: ["webapp:80"]
plugins: [deny_pages]
plugin:
deny_pages:
paths: [/admin, /private, /debug]
status_code: 403
```
### Multiple Plugins (with Cloudflare)
```yaml
labels:
easyhaproxy.http.host: secure-app.com
easyhaproxy.http.plugins: cloudflare,deny_pages
easyhaproxy.http.plugin.deny_pages.paths: /admin,/config
easyhaproxy.http.plugin.deny_pages.status_code: 403
```
### Environment Variables
| Environment Variable | Config Key | Type | Default | Description |
|---------------------------------------------|---------------|---------|---------|----------------------------------------|
| `EASYHAPROXY_PLUGIN_DENY_PAGES_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains |
| `EASYHAPROXY_PLUGIN_DENY_PAGES_PATHS` | `paths` | string | - | Comma-separated list of paths to block |
| `EASYHAPROXY_PLUGIN_DENY_PAGES_STATUS_CODE` | `status_code` | integer | `403` | HTTP status code to return |
## Generated HAProxy Configuration
```haproxy
# Deny Pages - Block specific paths
acl denied_path path_beg /admin /private /debug
http-request deny deny_status 404 if denied_path
```
## Important Notes
- The plugin runs once per domain during the discovery cycle
- Path matching uses `path_beg` (prefix matching), so `/admin` blocks `/admin/*` too
- Consider using `404` instead of `403` to hide the existence of blocked paths
- Works well in combination with other security plugins
## Related Documentation
- [Plugin System Overview](../../guides/plugins.md)
- [Container Labels Reference](../container-labels.md)

156
docs/reference/plugins/fastcgi.md Normal file
View file

@ -0,0 +1,156 @@
---
sidebar_position: 2
sidebar_label: "FastCGI"
---
# FastCGI Plugin
**Type:** Domain Plugin
**Runs:** Once for each discovered domain/host
## Overview
The FastCGI plugin configures HAProxy to communicate with PHP-FPM and other FastCGI applications. It automatically generates the necessary HAProxy `fcgi-app` configuration that defines CGI parameters for proper PHP-FPM communication.
## Why Use It
Automatically generates HAProxy `fcgi-app` configuration that defines required CGI parameters for PHP-FPM communication without manual HAProxy configuration.
## Configuration Options
| Option | Description | Default |
|-------------------|-----------------------------------------|------------------------------------|
| `enabled` | Enable/disable plugin | `true` |
| `document_root` | Document root path | `/etc/easyhaproxy/www` |
| `script_filename` | Custom pattern for SCRIPT_FILENAME | `%[path]` (uses HAProxy's default) |
| `index_file` | Default index file | `index.php` |
| `path_info` | Enable PATH_INFO support | `true` |
| `custom_params` | Dictionary of custom FastCGI parameters | (optional) |
## Configuration Examples
### Docker/Docker Compose (TCP connection)
```yaml
services:
php-fpm:
image: php:8.2-fpm
labels:
easyhaproxy.http.host: phpapp.local
easyhaproxy.http.port: 80
easyhaproxy.http.localport: 9000
easyhaproxy.http.proto: fcgi
easyhaproxy.http.plugins: fastcgi
easyhaproxy.http.plugin.fastcgi.document_root: /etc/easyhaproxy/www
easyhaproxy.http.plugin.fastcgi.index_file: index.php
volumes:
- ./app:/etc/easyhaproxy/www
```
### Docker/Docker Compose (Unix socket)
```yaml
services:
php-fpm:
image: php:8.2-fpm
labels:
easyhaproxy.http.host: phpapp.local
easyhaproxy.http.socket: /run/php/php-fpm.sock
easyhaproxy.http.proto: fcgi
easyhaproxy.http.plugins: fastcgi
easyhaproxy.http.plugin.fastcgi.document_root: /etc/easyhaproxy/www
easyhaproxy.http.plugin.fastcgi.index_file: index.php
volumes:
- ./app:/etc/easyhaproxy/www
- /run/php:/run/php
```
### Kubernetes Annotations
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
easyhaproxy.plugins: "fastcgi"
easyhaproxy.plugin.fastcgi.document_root: "/etc/easyhaproxy/www"
easyhaproxy.plugin.fastcgi.index_file: "index.php"
spec:
rules:
- host: phpapp.example.com
http:
paths:
- path: /
backend:
service:
name: php-fpm
port:
number: 9000
```
### Static YAML Configuration
```yaml
# /etc/easyhaproxy/static/config.yaml
easymapping:
- host: phpapp.local
port: 80
container: php-fpm:9000
proto: fcgi
plugins:
- fastcgi
plugin_config:
fastcgi:
document_root: /etc/easyhaproxy/www
index_file: index.php
path_info: true
```
### Environment Variables
| Environment Variable | Config Key | Type | Default | Description |
|----------------------------------------------|-------------------|----------|------------------------|---------------------------------------|
| `EASYHAPROXY_PLUGIN_FASTCGI_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains |
| `EASYHAPROXY_PLUGIN_FASTCGI_DOCUMENT_ROOT` | `document_root` | string | `/etc/easyhaproxy/www` | Document root path |
| `EASYHAPROXY_PLUGIN_FASTCGI_SCRIPT_FILENAME` | `script_filename` | string | `%[path]` | Custom pattern for SCRIPT_FILENAME |
| `EASYHAPROXY_PLUGIN_FASTCGI_INDEX_FILE` | `index_file` | string | `index.php` | Default index file |
| `EASYHAPROXY_PLUGIN_FASTCGI_PATH_INFO` | `path_info` | boolean | `true` | Enable PATH_INFO support |
## Generated HAProxy Configuration
```haproxy
# Top-level fcgi-app definition (added after defaults, before frontends/backends)
fcgi-app fcgi_phpapp_local
docroot /etc/easyhaproxy/www
index index.php
path-info ^(/.+\.php)(/.*)?$
# Backend configuration (added to the backend section)
backend srv_phpapp_local_80
use-fcgi-app fcgi_phpapp_local
server srv-0 172.19.0.3:9000 proto fcgi
```
## CGI Parameters
The plugin configures:
- ✅ **SCRIPT_FILENAME** - Path to PHP script
- ✅ **DOCUMENT_ROOT** - Document root directory
- ✅ **SCRIPT_NAME** - Script name from URL
- ✅ **REQUEST_URI** - Full request URI with query string
- ✅ **QUERY_STRING** - URL query parameters
- ✅ **REQUEST_METHOD** - HTTP method (GET, POST, etc.)
- ✅ **CONTENT_TYPE & CONTENT_LENGTH** - Request body info
- ✅ **SERVER_NAME & SERVER_PORT** - Server details
- ✅ **HTTPS** - SSL/TLS status
- ✅ **PATH_INFO** - Path information (optional)
## Important Notes
- **Required:** Use this plugin together with `proto: fcgi` parameter for complete PHP-FPM support
- The plugin runs once per domain during the discovery cycle
## Related Documentation
- [Plugin System Overview](../../guides/plugins.md)
- [Container Labels Reference](../container-labels.md)

121
docs/reference/plugins/ip-whitelist.md Normal file
View file

@ -0,0 +1,121 @@
---
sidebar_position: 4
sidebar_label: "IP Whitelist"
---
# IP Whitelist Plugin
**Type:** Domain Plugin
**Runs:** Once for each discovered domain/host
## Overview
The IP Whitelist plugin restricts access to a domain to only specific IP addresses or CIDR ranges.
## Why Use It
Restrict access to internal tools, admin panels, or staging environments to only trusted IP addresses.
## Configuration Options
| Option | Description | Default |
|---------------|--------------------------------------------------|------------|
| `enabled` | Enable/disable plugin | `true` |
| `allowed_ips` | Comma-separated list of IPs/CIDR ranges to allow | (required) |
| `status_code` | HTTP status code to return for blocked IPs | `403` |
## Configuration Examples
### Docker/Docker Compose (Basic)
```yaml
services:
admin:
labels:
easyhaproxy.http.host: admin.example.com
easyhaproxy.http.plugins: ip_whitelist
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: 192.168.1.0/24,10.0.0.5
easyhaproxy.http.plugin.ip_whitelist.status_code: 403
```
### Office Network Access
```yaml
labels:
easyhaproxy.http.host: admin.example.com
easyhaproxy.http.plugins: ip_whitelist
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: 203.0.113.0/24,198.51.100.42
```
### Kubernetes Annotations
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
easyhaproxy.plugins: "ip_whitelist"
easyhaproxy.plugin.ip_whitelist.allowed_ips: "192.168.1.0/24,10.0.0.5"
easyhaproxy.plugin.ip_whitelist.status_code: "403"
spec:
rules:
- host: admin.example.com
http:
paths:
- path: /
backend:
service:
name: admin-panel
port:
number: 80
```
### Static YAML Configuration
```yaml
easymapping:
- host: admin.example.com
port: 443
container: admin-panel:443
plugins:
- ip_whitelist
plugin_config:
ip_whitelist:
allowed_ips: 192.168.1.0/24,10.0.0.5
status_code: 403
```
### Environment Variables
| Environment Variable | Config Key | Type | Default | Description |
|-----------------------------------------------|---------------|----------|---------|--------------------------------------------------|
| `EASYHAPROXY_PLUGIN_IP_WHITELIST_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains |
| `EASYHAPROXY_PLUGIN_IP_WHITELIST_ALLOWED_IPS` | `allowed_ips` | string | - | Comma-separated list of IPs/CIDR ranges to allow |
| `EASYHAPROXY_PLUGIN_IP_WHITELIST_STATUS_CODE` | `status_code` | integer | `403` | HTTP status code to return for blocked IPs |
## Generated HAProxy Configuration
```haproxy
# IP Whitelist - Only allow specific IPs
acl whitelisted_ip src 192.168.1.0/24 10.0.0.5
http-request deny deny_status 403 if !whitelisted_ip
```
## IP Address Formats
The plugin supports:
- **Single IPs:** `10.0.0.5`, `203.0.113.42`
- **CIDR ranges:** `192.168.1.0/24`, `10.0.0.0/8`
- **Multiple entries:** Comma-separated list of IPs and/or CIDR ranges
## Important Notes
- **Warning:** This blocks ALL IPs except those in the whitelist. Make sure to include your own IP!
- The plugin runs once per domain during the discovery cycle
- Test thoroughly before deploying to production
- Consider using VPN CIDR ranges for remote access
## Related Documentation
- [Plugin System Overview](../../guides/plugins.md)
- [Container Labels Reference](../container-labels.md)

196
docs/reference/plugins/jwt-validator.md Normal file
View file

@ -0,0 +1,196 @@
---
sidebar_position: 1
sidebar_label: "JWT Validator"
---
# JWT Validator Plugin
**Type:** Domain Plugin
**Runs:** Once for each discovered domain/host
## Overview
The JWT Validator plugin validates JWT (JSON Web Token) authentication tokens using HAProxy's built-in JWT functionality.
## Why Use It
Protect APIs and services with JWT authentication without needing application-level code.
## Generating JWT Keys
```bash
# Generate RSA key pair (idempotent - skips if exists)
[ -f jwt_private.pem ] || openssl genrsa -out jwt_private.pem 2048
[ -f jwt_pubkey.pem ] || openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
```
## Configuration Options
| Option | Description | Default |
|-------------------|----------------------------------------------------------------------------------------------|-------------|
| `enabled` | Enable/disable plugin | `true` |
| `algorithm` | JWT signing algorithm | `RS256` |
| `issuer` | Expected JWT issuer (optional, set to `none`/`null` to skip validation) | (optional) |
| `audience` | Expected JWT audience (optional, set to `none`/`null` to skip validation) | (optional) |
| `pubkey_path` | Path to public key file (priority 1: explicit file path) | (optional) |
| `pubkey` | Public key content as base64-encoded string (priority 2: inline content) | (optional) |
| `k8s_secret.pubkey` | Kubernetes secret containing public key (priority 3: Kubernetes only) | (optional) |
| `paths` | List of paths that require JWT validation (optional) | (all paths) |
| `only_paths` | If `true`, only specified paths are accessible; if `false`, only specified paths require JWT | `false` |
| `allow_anonymous` | If `true`, allows requests without Authorization header (validates JWT if present) | `false` |
### Public Key Configuration Priority
When multiple public key options are configured, they are evaluated in this order:
1. **`pubkey_path`** - Direct file path (explicit configuration)
2. **`pubkey`** - Base64-encoded key content (inline configuration)
3. **`k8s_secret.pubkey`** - Kubernetes secret (recommended for Kubernetes deployments)
## Path Validation Logic
- **No paths configured:** ALL requests to the domain require JWT validation (default behavior)
- **Paths configured + `only_paths=false`:** Only specified paths require JWT validation, other paths pass through without validation
- **Paths configured + `only_paths=true`:** Only specified paths are accessible (with JWT validation), all other paths are denied
## Anonymous Access Logic
- **`allow_anonymous=false` (default):** Requests without `Authorization` header are denied
- **`allow_anonymous=true`:** Requests without `Authorization` header are allowed to pass through, but JWTs are validated if the header is present
## Configuration Examples
### Docker/Docker Compose (Protect All Paths)
```yaml
services:
api:
labels:
easyhaproxy.http.host: api.example.com
easyhaproxy.http.plugins: jwt_validator
easyhaproxy.http.plugin.jwt_validator.algorithm: RS256
easyhaproxy.http.plugin.jwt_validator.issuer: https://auth.example.com/
easyhaproxy.http.plugin.jwt_validator.audience: https://api.example.com
easyhaproxy.http.plugin.jwt_validator.pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
volumes:
- ./pubkey.pem:/etc/easyhaproxy/jwt_keys/api_pubkey.pem:ro
```
### Protect Specific Paths Only
```yaml
labels:
easyhaproxy.http.plugins: jwt_validator
easyhaproxy.http.plugin.jwt_validator.pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
easyhaproxy.http.plugin.jwt_validator.paths: /api/admin,/api/sensitive
easyhaproxy.http.plugin.jwt_validator.only_paths: false
# /api/health, /api/docs, etc. remain publicly accessible
```
### Only Allow Specific Paths
```yaml
labels:
easyhaproxy.http.plugins: jwt_validator
easyhaproxy.http.plugin.jwt_validator.pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
easyhaproxy.http.plugin.jwt_validator.paths: /api/public,/api/v1
easyhaproxy.http.plugin.jwt_validator.only_paths: true
# All paths except /api/public and /api/v1 are denied
```
### Kubernetes with Secrets (Recommended)
```yaml
---
apiVersion: v1
kind: Secret
metadata:
name: jwt-pubkey-secret
namespace: production
type: Opaque
stringData:
pubkey: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-ingress
namespace: production
annotations:
easyhaproxy.plugins: "jwt_validator"
easyhaproxy.plugin.jwt_validator.algorithm: "RS256"
easyhaproxy.plugin.jwt_validator.issuer: "https://auth.example.com/"
easyhaproxy.plugin.jwt_validator.audience: "https://api.example.com"
easyhaproxy.plugin.jwt_validator.k8s_secret.pubkey: "jwt-pubkey-secret"
easyhaproxy.plugin.jwt_validator.paths: "/api/admin,/api/users"
easyhaproxy.plugin.jwt_validator.only_paths: "false"
spec:
ingressClassName: easyhaproxy
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: api-service
port:
number: 8080
```
### Static YAML Configuration
```yaml
# /etc/easyhaproxy/static/config.yaml
containers:
"api.example.com:443":
ip: ["api-service:8080"]
ssl: true
plugins: [jwt_validator]
plugin:
jwt_validator:
algorithm: RS256
issuer: https://auth.example.com/
audience: https://api.example.com
pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
```
### Environment Variables
| Environment Variable | Config Key | Type | Default | Description |
|----------------------------------------------------|-------------------|---------|---------|---------------------------------------------|
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALGORITHM` | `algorithm` | string | `RS256` | JWT signing algorithm |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ISSUER` | `issuer` | string | - | Expected JWT issuer (optional) |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_AUDIENCE` | `audience` | string | - | Expected JWT audience (optional) |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY_PATH` | `pubkey_path` | string | - | Path to public key file |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY` | `pubkey` | string | - | Public key as base64-encoded string |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PATHS` | `paths` | string | - | Comma-separated paths requiring JWT |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ONLY_PATHS` | `only_paths` | boolean | `false` | If true, only specified paths accessible |
| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALLOW_ANONYMOUS` | `allow_anonymous` | boolean | `false` | Allow requests without Authorization header |
## What It Validates
- ✅ Authorization header presence
- ✅ JWT signing algorithm (RS256, RS512, etc.)
- ✅ JWT issuer (if configured)
- ✅ JWT audience (if configured)
- ✅ JWT signature using public key
- ✅ JWT expiration time
## Important Notes
- **Required:** HAProxy 2.5+ with JWT support
- Mount public key file as read-only volume
- The plugin runs once per domain during the discovery cycle
- Test thoroughly with your JWT provider before deploying to production
## Related Documentation
- [Plugin System Overview](../../guides/plugins.md)
- [Container Labels Reference](../container-labels.md)
- [Kubernetes Secrets](../../getting-started/kubernetes.md#loading-plugin-configuration-from-kubernetes-secrets)