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

@ -324,6 +324,292 @@ networks:
---
## Plugin Examples
### JWT Validator Plugin
Secure your API with JWT token validation in Swarm:
```yaml
version: "3"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- jwt_keys:/etc/haproxy/jwt_keys
deploy:
replicas: 1
environment:
EASYHAPROXY_DISCOVER: swarm
ports:
- "80:80/tcp"
- "443:443/tcp"
networks:
- easyhaproxy
api:
image: my-api:latest
deploy:
replicas: 5
labels:
easyhaproxy.http.host: "api.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# Enable JWT validation
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/haproxy/jwt_keys/api_pubkey.pem"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
volumes:
jwt_keys:
```
**Deploy public key using Docker config:**
```bash
# Create Docker config with public key
docker config create jwt_api_pubkey ./api_pubkey.pem
# Update EasyHAProxy service to use config
docker service update \
--config-add source=jwt_api_pubkey,target=/etc/haproxy/jwt_keys/api_pubkey.pem \
easyhaproxy_haproxy
```
**Test:**
```bash
# Without token
curl http://api.example.com/users
# Response: Missing Authorization HTTP header
# With valid token
curl -H "Authorization: Bearer eyJhbGc..." http://api.example.com/users
# Response: Success
```
---
### Cloudflare IP Restoration Plugin
Restore original visitor IPs in Swarm environment:
```yaml
version: "3"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
configs:
- source: cloudflare_ips
target: /etc/haproxy/cloudflare_ips.lst
deploy:
replicas: 1
environment:
EASYHAPROXY_DISCOVER: swarm
ports:
- "80:80/tcp"
- "443:443/tcp"
networks:
- easyhaproxy
webapp:
image: webapp:latest
deploy:
replicas: 3
labels:
easyhaproxy.http.host: "myapp.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# Enable Cloudflare plugin
easyhaproxy.http.plugins: "cloudflare"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
configs:
cloudflare_ips:
file: ./cloudflare_ips.lst
```
**Create Cloudflare IP list:**
```bash
# Download Cloudflare IPs
curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
# Deploy stack
docker stack deploy -c cloudflare-stack.yml myapp
```
---
### IP Whitelist Plugin
Restrict admin panel to specific IPs in Swarm:
```yaml
version: "3"
services:
admin:
image: admin-panel:latest
deploy:
replicas: 2
labels:
easyhaproxy.http.host: "admin.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "4000"
# Enable IP whitelist
easyhaproxy.http.plugins: "ip_whitelist"
# Allow office network and VPN
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,198.51.100.0/24,10.8.0.0/16"
easyhaproxy.http.plugin.ip_whitelist.status_code: "403"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
```
**Test:**
```bash
# From office IP (203.0.113.50)
curl http://admin.example.com
# Response: Success
# From home/blocked IP
curl http://admin.example.com
# Response: HTTP 403 Forbidden
```
---
### Multiple Plugins Combined
Production-ready setup with multiple security layers:
```yaml
version: "3"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
configs:
- source: cloudflare_ips
target: /etc/haproxy/cloudflare_ips.lst
- source: jwt_pubkey
target: /etc/haproxy/jwt_keys/api_pubkey.pem
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
environment:
EASYHAPROXY_DISCOVER: swarm
EASYHAPROXY_SSL_MODE: "loose"
EASYHAPROXY_CERTBOT_EMAIL: admin@example.com
ports:
- "80:80/tcp"
- "443:443/tcp"
- "1936:1936/tcp"
networks:
- easyhaproxy
# Public website with Cloudflare
website:
image: website:latest
deploy:
replicas: 4
labels:
easyhaproxy.http.host: "example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "3000"
easyhaproxy.http.certbot: "true"
easyhaproxy.http.redirect_ssl: "true"
# Cloudflare + block sensitive paths
easyhaproxy.http.plugins: "cloudflare,deny_pages"
easyhaproxy.http.plugin.deny_pages.paths: "/admin,/.env,/config"
easyhaproxy.http.plugin.deny_pages.status_code: "404"
networks:
- easyhaproxy
# Authenticated API with JWT
api:
image: api:latest
deploy:
replicas: 6
labels:
easyhaproxy.http.host: "api.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
easyhaproxy.http.certbot: "true"
# Cloudflare + JWT + block internal endpoints
easyhaproxy.http.plugins: "cloudflare,jwt_validator,deny_pages"
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/haproxy/jwt_keys/api_pubkey.pem"
easyhaproxy.http.plugin.deny_pages.paths: "/internal,/metrics"
networks:
- easyhaproxy
# Admin panel with strict IP restrictions
admin:
image: admin:latest
deploy:
replicas: 2
labels:
easyhaproxy.http.host: "admin.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "4000"
easyhaproxy.http.certbot: "true"
# IP whitelist only (no public access)
easyhaproxy.http.plugins: "ip_whitelist"
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24"
easyhaproxy.http.plugin.ip_whitelist.status_code: "403"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
configs:
cloudflare_ips:
file: ./cloudflare_ips.lst
jwt_pubkey:
file: ./api_pubkey.pem
```
**Deploy:**
```bash
docker stack deploy -c production-stack.yml production
```
**Security layers:**
- **Website**: Cloudflare IP restoration + path blocking
- **API**: Cloudflare + JWT validation + internal path blocking
- **Admin**: Strict IP whitelist (office network only)
---
## Scaling Services
Scale services dynamically:

View file

@ -0,0 +1,78 @@
# Cloudflare IP Restoration Plugin Example for Docker Swarm
#
# This example demonstrates restoring original visitor IPs when using Cloudflare CDN
#
# Prerequisites:
# 1. Docker Swarm initialized:
# docker swarm init
#
# 2. Create overlay network:
# docker network create --driver overlay --attachable easyhaproxy
#
# 3. Download Cloudflare IPs and create Docker config:
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
# docker config create cloudflare_ips cloudflare_ips.lst
#
# 4. Deploy the stack:
# docker stack deploy -c cloudflare.yml webapp
#
# 5. Test:
# curl http://<swarm-ip>/
#
# Note: This plugin is most useful when your site is actually behind Cloudflare.
version: "3.7"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
configs:
- source: cloudflare_ips
target: /etc/haproxy/cloudflare_ips.lst
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
environment:
EASYHAPROXY_DISCOVER: swarm
HAPROXY_USERNAME: admin
HAPROXY_PASSWORD: password
HAPROXY_STATS_PORT: 1936
ports:
- "80:80/tcp"
- "443:443/tcp"
- "1936:1936/tcp"
networks:
- easyhaproxy
# Web application behind Cloudflare
webapp:
image: byjg/static-httpserver
environment:
TITLE: "App Behind Cloudflare"
deploy:
replicas: 4
labels:
easyhaproxy.http.host: "myapp.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# Enable Cloudflare plugin
easyhaproxy.http.plugins: "cloudflare"
# Optional: Specify custom IP list path
# easyhaproxy.http.plugin.cloudflare.ip_list_path: "/etc/haproxy/cloudflare_ips.lst"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
configs:
cloudflare_ips:
external: true

View file

@ -0,0 +1,73 @@
# IP Whitelist Plugin Example for Docker Swarm
#
# This example demonstrates restricting access to specific IP addresses in Swarm
#
# Prerequisites:
# 1. Docker Swarm initialized:
# docker swarm init
#
# 2. Create overlay network:
# docker network create --driver overlay --attachable easyhaproxy
#
# 3. Update allowed_ips label with your actual IP addresses/networks
#
# 4. Deploy the stack:
# docker stack deploy -c ip-whitelist.yml admin
#
# 5. Test from allowed IP:
# curl http://<swarm-ip>/
# # Response: Success (200 OK)
#
# 6. Test from non-allowed IP:
# # Response: HTTP 403 Forbidden
version: "3.7"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
environment:
EASYHAPROXY_DISCOVER: swarm
HAPROXY_USERNAME: admin
HAPROXY_PASSWORD: password
HAPROXY_STATS_PORT: 1936
ports:
- "80:80/tcp"
- "1936:1936/tcp"
networks:
- easyhaproxy
# Admin panel with IP restrictions
admin:
image: byjg/static-httpserver
environment:
TITLE: "Admin Panel - IP Restricted"
deploy:
replicas: 3
labels:
easyhaproxy.http.host: "admin.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# Enable IP whitelist plugin
easyhaproxy.http.plugins: "ip_whitelist"
# Allow specific IPs and networks
# UPDATE THIS with your actual office/VPN IPs!
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,198.51.100.0/24,10.0.0.0/8"
# Status code to return for blocked IPs
easyhaproxy.http.plugin.ip_whitelist.status_code: "403"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true

View file

@ -0,0 +1,89 @@
# JWT Validator Plugin Example for Docker Swarm
#
# This example demonstrates JWT token validation for API protection in Swarm
#
# Prerequisites:
# 1. Docker Swarm initialized:
# docker swarm init
#
# 2. Create overlay network:
# docker network create --driver overlay --attachable easyhaproxy
#
# 3. Generate JWT keys and create Docker config:
# openssl genrsa -out jwt_private.pem 2048
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
# docker config create jwt_api_pubkey jwt_pubkey.pem
#
# 4. Deploy the stack:
# docker stack deploy -c jwt-validator.yml api
#
# 5. Test without token (should fail):
# curl http://<swarm-ip>/
# # Response: Missing Authorization HTTP header
#
# 6. 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
#
# 7. Test with token:
# TOKEN="eyJhbGc..."
# curl -H "Authorization: Bearer $TOKEN" http://<swarm-ip>/
# # Response: Success
version: "3.7"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
configs:
- source: jwt_api_pubkey
target: /etc/haproxy/jwt_keys/api_pubkey.pem
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
environment:
EASYHAPROXY_DISCOVER: swarm
HAPROXY_USERNAME: admin
HAPROXY_PASSWORD: password
HAPROXY_STATS_PORT: 1936
ports:
- "80:80/tcp"
- "1936:1936/tcp"
networks:
- easyhaproxy
# Protected API service
api:
image: byjg/static-httpserver
environment:
TITLE: "Protected API - JWT Required"
deploy:
replicas: 5
labels:
easyhaproxy.http.host: "api.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# Enable JWT validator plugin
easyhaproxy.http.plugins: "jwt_validator"
# JWT validator configuration
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/haproxy/jwt_keys/api_pubkey.pem"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
configs:
jwt_api_pubkey:
external: true

View file

@ -0,0 +1,137 @@
# Multiple Plugins Combined Example for Docker Swarm
#
# This example demonstrates using multiple plugins together for enhanced security
#
# Prerequisites:
# 1. Docker Swarm initialized:
# docker swarm init
#
# 2. Create overlay network:
# docker network create --driver overlay --attachable easyhaproxy
#
# 3. Generate JWT keys and create Docker config:
# openssl genrsa -out jwt_private.pem 2048
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
# docker config create jwt_api_pubkey jwt_pubkey.pem
#
# 4. Download Cloudflare IPs and create Docker config:
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
# docker config create cloudflare_ips cloudflare_ips.lst
#
# 5. Deploy the stack:
# docker stack deploy -c plugins-combined.yml production
#
# This creates three services with different security profiles:
# - Public website: Cloudflare + path blocking
# - Protected API: JWT validation + path blocking
# - Admin panel: Strict IP whitelist
version: "3.7"
services:
haproxy:
image: byjg/easy-haproxy:4.6.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
configs:
- source: cloudflare_ips
target: /etc/haproxy/cloudflare_ips.lst
- source: jwt_api_pubkey
target: /etc/haproxy/jwt_keys/api_pubkey.pem
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
environment:
EASYHAPROXY_DISCOVER: swarm
EASYHAPROXY_SSL_MODE: "loose"
HAPROXY_CUSTOMERRORS: "true"
HAPROXY_USERNAME: admin
HAPROXY_PASSWORD: password
HAPROXY_STATS_PORT: 1936
ports:
- "80:80/tcp"
- "443:443/tcp"
- "1936:1936/tcp"
networks:
- easyhaproxy
# Public website with Cloudflare + path blocking
website:
image: byjg/static-httpserver
environment:
TITLE: "Public Website"
deploy:
replicas: 4
labels:
easyhaproxy.http.host: "website.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# Cloudflare IP restoration + block sensitive paths
easyhaproxy.http.plugins: "cloudflare,deny_pages"
easyhaproxy.http.plugin.deny_pages.paths: "/admin,/wp-admin,/wp-login.php,/.env,/config"
easyhaproxy.http.plugin.deny_pages.status_code: "404"
networks:
- easyhaproxy
# Protected API with JWT + path blocking
api:
image: byjg/static-httpserver
environment:
TITLE: "Protected API"
deploy:
replicas: 6
labels:
easyhaproxy.http.host: "api.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# JWT validation + block internal endpoints
easyhaproxy.http.plugins: "jwt_validator,deny_pages"
# JWT configuration
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/haproxy/jwt_keys/api_pubkey.pem"
# Block internal/debug paths
easyhaproxy.http.plugin.deny_pages.paths: "/internal,/debug,/metrics"
easyhaproxy.http.plugin.deny_pages.status_code: "403"
networks:
- easyhaproxy
# Admin panel with strict IP whitelist
admin:
image: byjg/static-httpserver
environment:
TITLE: "Admin Panel"
deploy:
replicas: 2
labels:
easyhaproxy.http.host: "admin.example.com"
easyhaproxy.http.port: "80"
easyhaproxy.http.localport: "8080"
# IP whitelist only (strictest security)
easyhaproxy.http.plugins: "ip_whitelist"
# Only allow office network
# UPDATE with your actual office/VPN IPs!
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,10.0.0.0/8"
easyhaproxy.http.plugin.ip_whitelist.status_code: "403"
networks:
- easyhaproxy
networks:
easyhaproxy:
external: true
configs:
cloudflare_ips:
external: true
jwt_api_pubkey:
external: true