1
0
Fork 0

Add comprehensive plugin usage examples for Docker, Kubernetes, and Swarm

- Introduced multiple detailed plugin examples for Cloudflare IP restoration, IP whitelisting, JWT validation, and combined usage.
- Added configurations for `docker-compose`, `Kubernetes`, and `Swarm` showcasing individual and multi-plugin use cases.
- Included clear prerequisites, setup steps, and testing procedures for each example.
- Documented advanced scenarios like path blocking, custom IP lists, and JWT validation for production environments.
This commit is contained in:
Joao Gilberto Magalhaes 2025-11-27 19:08:48 -05:00
parent 06d1d447f8
commit f75cb8aab2
15 changed files with 1977 additions and 0 deletions

View file

@ -288,6 +288,275 @@ See [Using Plugins with Kubernetes](../../docs/kubernetes.md#using-plugins-with-
---
## Plugin Examples
### JWT Validator Plugin
Complete example with JWT validation for API protection:
```yaml
---
# Create ConfigMap with public key
apiVersion: v1
kind: ConfigMap
metadata:
name: jwt-keys
namespace: default
data:
api_pubkey.pem: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----
---
# Mount public key into EasyHAProxy pod
# Add this to your EasyHAProxy deployment:
# volumeMounts:
# - name: jwt-keys
# mountPath: /etc/haproxy/jwt_keys
# volumes:
# - name: jwt-keys
# configMap:
# name: jwt-keys
---
apiVersion: v1
kind: Service
metadata:
name: api-service
namespace: default
spec:
ports:
- port: 8080
selector:
app: api
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
spec:
containers:
- name: api
image: my-api:latest
ports:
- containerPort: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable JWT validator
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.pubkey_path: "/etc/haproxy/jwt_keys/api_pubkey.pem"
name: api-ingress
namespace: default
spec:
rules:
- host: api.example.com
http:
paths:
- backend:
service:
name: api-service
port:
number: 8080
pathType: ImplementationSpecific
```
**Test:**
```bash
# Without JWT token - should fail
curl http://api.example.com/users
# Response: Missing Authorization HTTP header
# With valid JWT token
TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -H "Authorization: Bearer $TOKEN" http://api.example.com/users
# Response: Success
```
---
### Cloudflare IP Restoration Plugin
Restore original visitor IPs when behind Cloudflare:
```yaml
---
# Create ConfigMap with Cloudflare IP ranges
apiVersion: v1
kind: ConfigMap
metadata:
name: cloudflare-ips
namespace: easyhaproxy
data:
cloudflare_ips.lst: |
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
---
# Mount ConfigMap into EasyHAProxy pod
# Add this to your EasyHAProxy deployment:
# volumeMounts:
# - name: cloudflare-ips
# mountPath: /etc/haproxy/cloudflare_ips.lst
# subPath: cloudflare_ips.lst
# volumes:
# - name: cloudflare-ips
# configMap:
# name: cloudflare-ips
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable Cloudflare plugin
easyhaproxy.plugins: "cloudflare"
name: webapp-ingress
namespace: default
spec:
rules:
- host: myapp.example.com
http:
paths:
- backend:
service:
name: webapp-service
port:
number: 8080
pathType: ImplementationSpecific
```
**Download latest Cloudflare IPs:**
```bash
curl https://www.cloudflare.com/ips-v4
curl https://www.cloudflare.com/ips-v6
```
---
### IP Whitelist Plugin
Restrict admin panel to office IPs only:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable IP whitelist
easyhaproxy.plugins: "ip_whitelist"
easyhaproxy.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,198.51.100.42"
easyhaproxy.plugin.ip_whitelist.status_code: "403"
name: admin-ingress
namespace: default
spec:
rules:
- host: admin.example.com
http:
paths:
- backend:
service:
name: admin-service
port:
number: 8080
pathType: ImplementationSpecific
```
**Test:**
```bash
# From allowed IP (203.0.113.50)
curl http://admin.example.com
# Response: Success
# From blocked IP
curl http://admin.example.com
# Response: HTTP 403 Forbidden
```
---
### Multiple Plugins Combined
Combine Cloudflare + JWT + Path Blocking for maximum security:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable multiple plugins
easyhaproxy.plugins: "cloudflare,jwt_validator,deny_pages"
# Cloudflare - restore real IPs
# (no config needed if using default path)
# JWT Validator - validate tokens
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.pubkey_path: "/etc/haproxy/jwt_keys/api_pubkey.pem"
# Deny Pages - block sensitive paths
easyhaproxy.plugin.deny_pages.paths: "/internal,/debug,/admin"
easyhaproxy.plugin.deny_pages.status_code: "404"
name: secure-api-ingress
namespace: production
spec:
rules:
- host: api.example.com
http:
paths:
- backend:
service:
name: api-service
port:
number: 8080
pathType: ImplementationSpecific
```
**Plugin execution order:**
1. Cloudflare IP restoration (sets correct visitor IP)
2. Deny Pages (blocks blacklisted paths)
3. JWT Validator (validates authentication)
---
## Creating SSL Secrets
### From Certificate Files

View file

@ -0,0 +1,103 @@
# Cloudflare IP Restoration Plugin Example for Kubernetes
#
# This example demonstrates restoring original visitor IPs when using Cloudflare CDN
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
#
# 2. Download Cloudflare IP ranges and create ConfigMap:
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
# kubectl create configmap cloudflare-ips \
# --from-file=cloudflare_ips.lst=cloudflare_ips.lst \
# -n easyhaproxy
#
# 3. Mount the ConfigMap in EasyHAProxy deployment (add to volumeMounts and volumes):
# volumeMounts:
# - name: cloudflare-ips
# mountPath: /etc/haproxy/cloudflare_ips.lst
# subPath: cloudflare_ips.lst
# volumes:
# - name: cloudflare-ips
# configMap:
# name: cloudflare-ips
#
# 4. Apply this manifest:
# kubectl apply -f cloudflare.yml
#
# 5. Test:
# curl http://myapp.example.local/
#
# Note: This plugin is most useful when your site is actually behind Cloudflare.
---
apiVersion: v1
kind: Service
metadata:
name: webapp-service
namespace: default
spec:
ports:
- port: 8080
targetPort: 8080
selector:
app: webapp
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: byjg/static-httpserver
ports:
- containerPort: 8080
env:
- name: TITLE
value: "App Behind Cloudflare"
resources:
limits:
cpu: '0.1'
memory: '64Mi'
requests:
cpu: '0.05'
memory: '32Mi'
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable Cloudflare plugin
easyhaproxy.plugins: "cloudflare"
# Optional: Specify custom IP list path
# easyhaproxy.plugin.cloudflare.ip_list_path: "/etc/haproxy/cloudflare_ips.lst"
name: webapp-ingress-cloudflare
namespace: default
spec:
rules:
- host: myapp.example.local
http:
paths:
- backend:
service:
name: webapp-service
port:
number: 8080
pathType: ImplementationSpecific

View file

@ -0,0 +1,96 @@
# IP Whitelist Plugin Example for Kubernetes
#
# This example demonstrates restricting access to specific IP addresses
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
#
# 2. Update the allowed_ips annotation with your actual IP addresses/networks
#
# 3. Apply this manifest:
# kubectl apply -f ip-whitelist.yml
#
# 4. Test from allowed IP:
# curl http://admin.example.local/
# # Response: Success (200 OK)
#
# 5. Test from non-allowed IP:
# # Response: HTTP 403 Forbidden
#
# Note: Update the allowed_ips annotation with your actual office/VPN IPs
---
apiVersion: v1
kind: Service
metadata:
name: admin-service
namespace: default
spec:
ports:
- port: 8080
targetPort: 8080
selector:
app: admin
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: admin
namespace: default
spec:
replicas: 2
selector:
matchLabels:
app: admin
template:
metadata:
labels:
app: admin
spec:
containers:
- name: admin
image: byjg/static-httpserver
ports:
- containerPort: 8080
env:
- name: TITLE
value: "Admin Panel - IP Restricted"
resources:
limits:
cpu: '0.1'
memory: '64Mi'
requests:
cpu: '0.05'
memory: '32Mi'
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable IP whitelist plugin
easyhaproxy.plugins: "ip_whitelist"
# Allow specific IPs and networks
# UPDATE THIS with your actual office/VPN IPs!
easyhaproxy.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,198.51.100.42,10.0.0.0/8"
# Status code to return for blocked IPs
easyhaproxy.plugin.ip_whitelist.status_code: "403"
name: admin-ingress-whitelist
namespace: default
spec:
rules:
- host: admin.example.local
http:
paths:
- backend:
service:
name: admin-service
port:
number: 8080
pathType: ImplementationSpecific

View file

@ -0,0 +1,113 @@
# JWT Validator Plugin Example for Kubernetes
#
# This example demonstrates JWT token validation for API protection in Kubernetes
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
# 2. Generate RSA key pair:
# openssl genrsa -out jwt_private.pem 2048
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
#
# 3. Create ConfigMap with public key:
# kubectl create configmap jwt-keys --from-file=api_pubkey.pem=jwt_pubkey.pem
#
# 4. Mount the ConfigMap in EasyHAProxy deployment (add to volumeMounts and volumes):
# volumeMounts:
# - name: jwt-keys
# mountPath: /etc/haproxy/jwt_keys
# volumes:
# - name: jwt-keys
# configMap:
# name: jwt-keys
#
# 5. Apply this manifest:
# kubectl apply -f jwt-validator.yml
#
# 6. Test without token (should fail):
# curl http://api.example.local/
# # Response: Missing Authorization HTTP header
#
# 7. Generate test JWT at https://jwt.io with:
# - Algorithm: RS256
# - Payload: {"iss":"https://auth.example.com/","aud":"https://api.example.com","exp":9999999999}
# - Use your jwt_private.pem for signing
#
# 8. Test with token:
# TOKEN="eyJhbGc..."
# curl -H "Authorization: Bearer $TOKEN" http://api.example.local/
# # Response: Success
---
apiVersion: v1
kind: Service
metadata:
name: api-service
namespace: default
spec:
ports:
- port: 8080
targetPort: 8080
selector:
app: api
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
spec:
containers:
- name: api
image: byjg/static-httpserver
ports:
- containerPort: 8080
env:
- name: TITLE
value: "Protected API - JWT Required"
resources:
limits:
cpu: '0.1'
memory: '64Mi'
requests:
cpu: '0.05'
memory: '32Mi'
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable JWT validator plugin
easyhaproxy.plugins: "jwt_validator"
# JWT validator configuration
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.pubkey_path: "/etc/haproxy/jwt_keys/api_pubkey.pem"
name: api-ingress-jwt
namespace: default
spec:
rules:
- host: api.example.local
http:
paths:
- backend:
service:
name: api-service
port:
number: 8080
pathType: ImplementationSpecific

View file

@ -0,0 +1,233 @@
# Multiple Plugins Combined Example for Kubernetes
#
# This example demonstrates using multiple plugins together for enhanced security
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
#
# 2. Generate JWT keys and create ConfigMap:
# openssl genrsa -out jwt_private.pem 2048
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
# kubectl create configmap jwt-keys --from-file=api_pubkey.pem=jwt_pubkey.pem
#
# 3. Download Cloudflare IPs and create ConfigMap:
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
# kubectl create configmap cloudflare-ips \
# --from-file=cloudflare_ips.lst=cloudflare_ips.lst \
# -n easyhaproxy
#
# 4. Mount ConfigMaps in EasyHAProxy deployment
#
# 5. Apply this manifest:
# kubectl apply -f plugins-combined.yml
#
# This creates three services with different security profiles:
# - Public website: Cloudflare + path blocking
# - Protected API: JWT validation + path blocking
# - Admin panel: Strict IP whitelist
---
# Public website service
apiVersion: v1
kind: Service
metadata:
name: website-service
namespace: default
spec:
ports:
- port: 8080
selector:
app: website
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: website
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: website
template:
metadata:
labels:
app: website
spec:
containers:
- name: website
image: byjg/static-httpserver
env:
- name: TITLE
value: "Public Website"
resources:
requests:
cpu: '0.05'
memory: '32Mi'
---
# Public website ingress with Cloudflare + path blocking
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Cloudflare IP restoration + deny pages
easyhaproxy.plugins: "cloudflare,deny_pages"
easyhaproxy.plugin.deny_pages.paths: "/admin,/wp-admin,/wp-login.php,/.env,/config"
easyhaproxy.plugin.deny_pages.status_code: "404"
name: website-ingress
namespace: default
spec:
rules:
- host: website.example.local
http:
paths:
- backend:
service:
name: website-service
port:
number: 8080
pathType: ImplementationSpecific
---
# API service
apiVersion: v1
kind: Service
metadata:
name: api-service
namespace: default
spec:
ports:
- port: 8080
selector:
app: api
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: default
spec:
replicas: 5
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
spec:
containers:
- name: api
image: byjg/static-httpserver
env:
- name: TITLE
value: "Protected API"
resources:
requests:
cpu: '0.05'
memory: '32Mi'
---
# API ingress with JWT + path blocking
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# JWT validation + block internal endpoints
easyhaproxy.plugins: "jwt_validator,deny_pages"
# JWT config
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.pubkey_path: "/etc/haproxy/jwt_keys/api_pubkey.pem"
# Block internal paths
easyhaproxy.plugin.deny_pages.paths: "/internal,/debug,/metrics"
easyhaproxy.plugin.deny_pages.status_code: "403"
name: api-ingress
namespace: default
spec:
rules:
- host: api.example.local
http:
paths:
- backend:
service:
name: api-service
port:
number: 8080
pathType: ImplementationSpecific
---
# Admin service
apiVersion: v1
kind: Service
metadata:
name: admin-service
namespace: default
spec:
ports:
- port: 8080
selector:
app: admin
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: admin
namespace: default
spec:
replicas: 2
selector:
matchLabels:
app: admin
template:
metadata:
labels:
app: admin
spec:
containers:
- name: admin
image: byjg/static-httpserver
env:
- name: TITLE
value: "Admin Panel"
resources:
requests:
cpu: '0.05'
memory: '32Mi'
---
# Admin ingress with strict IP whitelist
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# IP whitelist only (strictest security)
easyhaproxy.plugins: "ip_whitelist"
# UPDATE with your office/VPN IPs!
easyhaproxy.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,10.0.0.0/8"
easyhaproxy.plugin.ip_whitelist.status_code: "403"
name: admin-ingress
namespace: default
spec:
rules:
- host: admin.example.local
http:
paths:
- backend:
service:
name: admin-service
port:
number: 8080
pathType: ImplementationSpecific