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

Revamp Swarm example documentation and streamline deployment instructions

Browse source 
- Consolidated and simplified Swarm example README to focus on YAML header comments for documentation.
- Removed redundant and extended sections, replacing with concise steps for getting started.
- Standardized YAML headers across `easyhaproxy.yml`, `services.yml`, and `portainer.yml` with a clearer and more readable format.
- Enhanced user guidance for deployment, setup requirements, verification, and cleanup.
This commit is contained in:
Joao Gilberto Magalhaes 2025-12-04 10:07:17 -05:00
parent 5397f0166e
commit b9a9bee0b9
29 changed files with 1459 additions and 2861 deletions
Download patch file Download diff file Expand all files Collapse all files

719
examples/kubernetes/README.md
View file

@ -1,705 +1,50 @@
# Kubernetes Examples
This directory contains Kubernetes manifest examples demonstrating EasyHAProxy ingress configurations.
Self-contained examples for EasyHAProxy ingress controller. **All documentation is in the YAML files as header comments.**
## Quick Start
1. Pick an example below
2. Open the YAML file
3. Read the header comments for complete instructions
4. Run the commands step-by-step
## Prerequisites
1. **Generate SSL Certificates (Required for TLS examples):**
```bash
# From the repository root
./examples/generate-keys.sh
```
All examples require:
- EasyHAProxy installed in your Kubernetes cluster
- Node labeled for EasyHAProxy deployment
This script automatically generates:
- SSL certificates for testing (host1.local, host2.local)
- JWT keys for authentication examples
- All other .pem files needed for examples
See header comments in each file for detailed setup instructions.
**Note:** These are self-signed certificates for testing only. For production, use Let's Encrypt or your own certificates.
## Basic Examples
2. **EasyHAProxy installed in your cluster:**
```bash
kubectl create namespace easyhaproxy
kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
```
3. **Label the node where EasyHAProxy will run:**
```bash
kubectl label nodes <node-name> "easyhaproxy/node=master"
```
See the [Kubernetes Guide](../../docs/kubernetes.md) for complete installation instructions.
---
## Examples Overview
### 1. Basic Ingress (`service.yml`)
**What it demonstrates:**
- Basic ingress configuration
- Multiple domains pointing to same service
- Complete deployment + service + ingress setup
**Components:**
- **Deployment**: `byjg/static-httpserver` container
- **Service**: ClusterIP exposing port 8080
- **Ingress**: Routes for `example.org` and `www.example.org`
**Apply:**
```bash
kubectl apply -f service.yml
```
**Test:**
```bash
# If using NodePort or port-forward:
curl -H "Host: example.org" http://<node-ip>:31080
# Or port-forward for testing:
kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8080:80
curl -H "Host: example.org" http://localhost:8080
```
**Manifest breakdown:**
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress # Required!
name: container-example
spec:
rules:
- host: example.org # First domain
http:
paths:
- backend:
service:
name: container-example
port:
number: 8080
- host: www.example.org # Second domain (same service)
...
```
---
### 2. TLS/SSL Ingress (`service_tls.yml`)
**What it demonstrates:**
- HTTPS/TLS configuration
- Custom SSL certificates via Kubernetes secrets
- SSL redirect (HTTP → HTTPS)
- Certbot/Let's Encrypt integration
**Components:**
- **Secret**: Custom SSL certificate for `host2.local`
- **Ingress**: TLS configuration + certbot annotation
**Apply:**
```bash
kubectl apply -f service_tls.yml
```
**Features:**
1. **Custom SSL Certificate:**
```yaml
apiVersion: v1
kind: Secret
metadata:
name: host2-tls
data:
tls.crt: <base64-encoded-certificate>
tls.key: <base64-encoded-private-key>
type: kubernetes.io/tls
```
2. **Ingress TLS Configuration:**
```yaml
spec:
tls:
- hosts:
- host2.local
secretName: host2-tls # References the secret above
```
3. **Certbot/Let's Encrypt:**
```yaml
metadata:
annotations:
easyhaproxy.certbot: 'true'
easyhaproxy.redirect_ssl: 'true'
```
**Test:**
```bash
# Test HTTPS (if host2.local in /etc/hosts)
curl -k https://host2.local
# Test HTTP redirect
curl -I http://host2.local
# Should return: HTTP/1.1 301 Moved Permanently
```
---
## Kubernetes Annotations Reference
All annotations are applied at the **Ingress** level and affect all hosts in that ingress.
### Required Annotation
| Annotation | Description | Example |
|-------------------------------|-----------------------|-----------------------|
| `kubernetes.io/ingress.class` | Activates EasyHAProxy | `easyhaproxy-ingress` |
### Optional Annotations
| Annotation | Description | Default | Example |
|----------------------------|----------------------|---------|-------------------------|
| `easyhaproxy.redirect_ssl` | Force HTTPS redirect | `false` | `'true'` |
| `easyhaproxy.certbot` | Enable Let's Encrypt | `false` | `'true'` |
| `easyhaproxy.mode` | Protocol mode | `http` | `http` or `tcp` |
| `easyhaproxy.listen_port` | Override listen port | `80` | `8080` |
| `easyhaproxy.plugins` | Enable plugins | - | `cloudflare,deny_pages` |
See [Kubernetes Guide](../../docs/kubernetes.md#kubernetes-annotations) for complete reference.
---
## Common Use Cases
### Use Case 1: Simple HTTP Application
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
name: my-app
spec:
rules:
- host: myapp.example.com
http:
paths:
- backend:
service:
name: my-app-service
port:
number: 8080
pathType: ImplementationSpecific
```
### Use Case 2: HTTPS with Let's Encrypt
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
easyhaproxy.certbot: 'true'
easyhaproxy.redirect_ssl: 'true'
name: secure-app
spec:
rules:
- host: secure.example.com
http:
paths:
- backend:
service:
name: secure-app-service
port:
number: 8080
pathType: ImplementationSpecific
```
**Requirements for Let's Encrypt:**
- Cluster must be publicly accessible on ports 80 and 443
- DNS must point to cluster IP
- Configure certbot email:
```bash
# Via Helm:
helm upgrade ingress byjg/easyhaproxy \
--set easyhaproxy.certbot.email=your-email@example.com
# Or via environment variable in manifest
```
### Use Case 3: Custom SSL Certificate
```yaml
---
apiVersion: v1
kind: Secret
metadata:
name: my-tls-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTi... # base64 encoded certificate
tls.key: LS0tLS1CRUdJTi... # base64 encoded private key
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
name: custom-ssl-app
spec:
tls:
- hosts:
- myapp.example.com
secretName: my-tls-secret
rules:
- host: myapp.example.com
http:
paths:
- backend:
service:
name: my-app-service
port:
number: 8080
pathType: ImplementationSpecific
```
### Use Case 4: Using Plugins (JWT, IP Whitelist, etc.)
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: easyhaproxy-ingress
# Enable plugins
easyhaproxy.plugins: "jwt_validator,deny_pages"
# Configure 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"
# Configure deny_pages
easyhaproxy.plugin.deny_pages.paths: "/admin,/private"
name: secure-api
spec:
rules:
- host: api.example.com
http:
paths:
- backend:
service:
name: api-service
port:
number: 8080
pathType: ImplementationSpecific
```
See [Using Plugins with Kubernetes](../../docs/kubernetes.md#using-plugins-with-kubernetes) for more examples.
---
| File | Description |
|------------------------------------|--------------------------------------------|
| [service.yml](service.yml) | Basic HTTP ingress with multiple domains |
| [service_tls.yml](service_tls.yml) | HTTPS/TLS ingress with custom certificates |
## Plugin Examples
### JWT Validator Plugin
| File | Description |
|----------------------------------------------|-----------------------------------------------------|
| [jwt-validator.yml](jwt-validator.yml) | JWT token validation for API protection |
| [ip-whitelist.yml](ip-whitelist.yml) | IP whitelist for admin panels or sensitive services |
| [cloudflare.yml](cloudflare.yml) | Restore real client IPs when behind Cloudflare CDN |
| [plugins-combined.yml](plugins-combined.yml) | Multiple plugins combined for layered security |
Complete example with JWT validation for API protection:
## Documentation Structure
```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-----
Each YAML file contains:
- **WHAT THIS DEMONSTRATES** - Key features and concepts
- **REQUIREMENTS** - Idempotent setup commands (safe to run multiple times)
- **HOW TO START** - Command to apply the manifest
- **HOW TO VERIFY IT'S WORKING** - Test commands with expected outputs
- **CLEAN UP** - Commands to remove resources
---
# 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
```bash
kubectl create secret tls my-tls-secret \
--cert=path/to/cert.crt \
--key=path/to/cert.key \
-n default
```
### From PEM File
```bash
# Extract certificate and key
openssl x509 -in cert.pem -out cert.crt
openssl rsa -in cert.pem -out cert.key
# Create secret
kubectl create secret tls my-tls-secret \
--cert=cert.crt \
--key=cert.key \
-n default
```
### Generate Self-Signed Certificate for Testing
```bash
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout tls.key -out tls.crt \
-subj "/CN=myapp.example.com"
kubectl create secret tls my-tls-secret \
--cert=tls.crt \
--key=tls.key
```
---
## Troubleshooting
### Ingress Not Detected
**Check annotation:**
```bash
kubectl get ingress <name> -o yaml | grep annotations -A 5
```
Ensure `kubernetes.io/ingress.class: easyhaproxy-ingress` is present.
**Check EasyHAProxy logs:**
```bash
kubectl logs -n easyhaproxy deployment/easyhaproxy -f
```
### SSL Certificate Not Loading
**Verify secret exists:**
```bash
kubectl get secret <secret-name> -o yaml
```
**Check secret has correct fields:**
- `tls.crt`: base64-encoded certificate
- `tls.key`: base64-encoded private key
**Check EasyHAProxy logs** for certificate loading errors.
### Let's Encrypt Fails
**Requirements:**
- Ports 80 and 443 must be publicly accessible
- DNS must resolve to cluster IP
- Certbot email must be configured
**Check certbot logs:**
```bash
kubectl logs -n easyhaproxy deployment/easyhaproxy | grep certbot
```
### Changes Not Applied
EasyHAProxy watches ingress changes automatically. If changes aren't applied:
1. **Check discovery interval:**
```bash
# Default is 10 seconds, increase if needed
EASYHAPROXY_REFRESH: "30"
```
2. **Force reload:**
```bash
kubectl rollout restart -n easyhaproxy deployment/easyhaproxy
```
---
## Tips
1. **Local Testing:**
Add entries to `/etc/hosts`:
```
<node-ip> example.org www.example.org host2.local
```
2. **View HAProxy Config:**
```bash
kubectl exec -n easyhaproxy deployment/easyhaproxy -- cat /etc/haproxy/haproxy.cfg
```
3. **Access Stats Interface:**
```bash
kubectl port-forward -n easyhaproxy deployment/easyhaproxy 1936:1936
# Open: http://localhost:1936
```
4. **Debug Mode:**
Enable debug logging:
```yaml
env:
- name: EASYHAPROXY_LOG_LEVEL
value: DEBUG
```
---
## Further Reading
## Additional Documentation
- [Kubernetes Installation Guide](../../docs/kubernetes.md)
- [Helm Installation](../../docs/helm.md)
- [Kubernetes Annotations Reference](../../docs/kubernetes.md#kubernetes-annotations)
- [Using Plugins with Kubernetes](../../docs/kubernetes.md#using-plugins-with-kubernetes)
- [ACME/Let's Encrypt](../../docs/acme.md)
- [Environment Variables](../../docs/environment-variable.md)

79
examples/kubernetes/cloudflare.yml
View file

@ -1,34 +1,65 @@
# Cloudflare IP Restoration Plugin Example for Kubernetes
# ==============================================================================
# EXAMPLE: Cloudflare IP Restoration Plugin for Kubernetes
# ==============================================================================
#
# This example demonstrates restoring original visitor IPs when using Cloudflare CDN
# WHAT THIS DEMONSTRATES:
# - Restoring original visitor IPs when behind Cloudflare CDN
# - Using ConfigMaps to mount Cloudflare IP ranges
# - Detecting requests from Cloudflare IP ranges
# - Accurate client IP logging for applications behind Cloudflare
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
# REQUIREMENTS (run these first):
# ```bash
# # 1. Ensure EasyHAProxy is installed in your cluster
# kubectl create namespace easyhaproxy
# kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
#
# 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
# # 2. Download Cloudflare IP ranges
# curl -s https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
# curl -s https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
#
# 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
# # 3. Create ConfigMap with Cloudflare IPs
# kubectl create configmap cloudflare-ips \
# --from-file=cloudflare_ips.lst=cloudflare_ips.lst \
# -n easyhaproxy
#
# 4. Apply this manifest:
# kubectl apply -f cloudflare.yml
# # 4. Mount the ConfigMap in EasyHAProxy deployment:
# # Edit your EasyHAProxy deployment and add:
# # volumeMounts:
# # - name: cloudflare-ips
# # mountPath: /etc/haproxy/cloudflare_ips.lst
# # subPath: cloudflare_ips.lst
# # volumes:
# # - name: cloudflare-ips
# # configMap:
# # name: cloudflare-ips
# ```
#
# 5. Test:
# curl http://myapp.example.local/
# HOW TO START:
# ```bash
# kubectl apply -f cloudflare.yml
# ```
#
# Note: This plugin is most useful when your site is actually behind Cloudflare.
# HOW TO VERIFY IT'S WORKING:
# ```bash
# # Check resources are created
# kubectl get deployment,service,ingress -l app=webapp
#
# # Test via port-forward
# kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8080:80
# curl -H "Host: myapp.example.local" http://localhost:8080
# # Expected: 200 OK with "App Behind Cloudflare"
#
# # In production behind Cloudflare, the plugin will restore real client IPs
# # from the CF-Connecting-IP header
# ```
#
# CLEAN UP:
# ```bash
# kubectl delete -f cloudflare.yml
# ```
#
# ==============================================================================
---
apiVersion: v1

51
examples/kubernetes/ip-whitelist.yml
View file

@ -1,23 +1,48 @@
# IP Whitelist Plugin Example for Kubernetes
# ==============================================================================
# EXAMPLE: IP Whitelist Plugin for Kubernetes
# ==============================================================================
#
# This example demonstrates restricting access to specific IP addresses
# WHAT THIS DEMONSTRATES:
# - Restricting access to specific IP addresses or CIDR ranges
# - Using annotations for IP-based access control
# - Protecting admin panels or sensitive services in Kubernetes
# - Custom HTTP status code for blocked requests
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
# REQUIREMENTS (run these first):
# ```bash
# # 1. Ensure EasyHAProxy is installed in your cluster
# kubectl create namespace easyhaproxy
# kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
#
# 2. Update the allowed_ips annotation with your actual IP addresses/networks
# # 2. IMPORTANT: Edit this file (line 80) and update allowed_ips
# # with your actual office/VPN IP addresses or networks
# ```
#
# 3. Apply this manifest:
# kubectl apply -f ip-whitelist.yml
# HOW TO START:
# ```bash
# kubectl apply -f ip-whitelist.yml
# ```
#
# 4. Test from allowed IP:
# curl http://admin.example.local/
# # Response: Success (200 OK)
# HOW TO VERIFY IT'S WORKING:
# ```bash
# # Check resources are created
# kubectl get deployment,service,ingress -l app=admin
#
# 5. Test from non-allowed IP:
# # Response: HTTP 403 Forbidden
# # Test from allowed IP
# kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8080:80
# curl -H "Host: admin.example.local" http://localhost:8080
# # Expected: 200 OK with "Admin Panel - IP Restricted" (if your IP is in allowed_ips)
#
# Note: Update the allowed_ips annotation with your actual office/VPN IPs
# # Test from non-allowed IP
# # Expected: HTTP 403 Forbidden
# ```
#
# CLEAN UP:
# ```bash
# kubectl delete -f ip-whitelist.yml
# ```
#
# ==============================================================================
---
apiVersion: v1

88
examples/kubernetes/jwt-validator.yml
View file

@ -1,41 +1,69 @@
# JWT Validator Plugin Example for Kubernetes
# ==============================================================================
# EXAMPLE: JWT Validator Plugin for Kubernetes
# ==============================================================================
#
# This example demonstrates JWT token validation for API protection in Kubernetes
# WHAT THIS DEMONSTRATES:
# - JWT token validation for API protection in Kubernetes
# - RS256 algorithm signature verification
# - Using ConfigMaps to mount JWT public keys
# - Issuer and audience validation
#
# 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
# REQUIREMENTS (run these first):
# ```bash
# # 1. Ensure EasyHAProxy is installed in your cluster
# kubectl create namespace easyhaproxy
# kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
#
# 3. Create ConfigMap with public key:
# kubectl create configmap jwt-keys --from-file=api_pubkey.pem=jwt_pubkey.pem
# # 2. 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
#
# 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
# # 3. Create ConfigMap with public key
# kubectl create configmap jwt-keys --from-file=api_pubkey.pem=jwt_pubkey.pem
#
# 5. Apply this manifest:
# kubectl apply -f jwt-validator.yml
# # 4. Mount the ConfigMap in EasyHAProxy deployment:
# # Edit your EasyHAProxy deployment and add:
# # volumeMounts:
# # - name: jwt-keys
# # mountPath: /etc/haproxy/jwt_keys
# # volumes:
# # - name: jwt-keys
# # configMap:
# # name: jwt-keys
# ```
#
# 6. Test without token (should fail):
# curl http://api.example.local/
# # Response: Missing Authorization HTTP header
# HOW TO START:
# ```bash
# kubectl apply -f jwt-validator.yml
# ```
#
# 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
# HOW TO VERIFY IT'S WORKING:
# ```bash
# # Check resources are created
# kubectl get deployment,service,ingress -l app=api
#
# 8. Test with token:
# TOKEN="eyJhbGc..."
# curl -H "Authorization: Bearer $TOKEN" http://api.example.local/
# # Response: Success
# # Test without token (should fail)
# kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8080:80
# curl -H "Host: api.example.local" http://localhost:8080
# # Expected: HTTP 403 - Missing Authorization HTTP header
#
# # Generate test JWT at https://jwt.io with:
# # - Algorithm: RS256
# # - Payload: {"iss":"https://auth.example.com/","aud":"https://api.example.com","exp":9999999999}
# # - Paste contents of jwt_private.pem in private key field
#
# # Test with valid token
# TOKEN="eyJhbGc..." # Replace with your generated token
# curl -H "Authorization: Bearer $TOKEN" -H "Host: api.example.local" http://localhost:8080
# # Expected: 200 OK with "Protected API - JWT Required"
# ```
#
# CLEAN UP:
# ```bash
# kubectl delete -f jwt-validator.yml
# ```
#
# ==============================================================================
---
apiVersion: v1

81
examples/kubernetes/plugins-combined.yml
View file

@ -1,31 +1,70 @@
# Multiple Plugins Combined Example for Kubernetes
# ==============================================================================
# EXAMPLE: Multiple Plugins Combined for Kubernetes
# ==============================================================================
#
# This example demonstrates using multiple plugins together for enhanced security
# WHAT THIS DEMONSTRATES:
# - Using multiple security plugins together
# - Different plugin combinations for different services
# - Layered security approach in Kubernetes
# - Three services with different security profiles:
# 1. Public website: Cloudflare + path blocking
# 2. Protected API: JWT validation + path blocking
# 3. Admin panel: Strict IP whitelist
#
# Prerequisites:
# 1. EasyHAProxy installed in your cluster
# REQUIREMENTS (run these first):
# ```bash
# # 1. Ensure EasyHAProxy is installed in your cluster
# kubectl create namespace easyhaproxy
# kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
#
# 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
# # 2. Generate JWT keys (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
# 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
# # 3. Download Cloudflare IPs
# curl -s https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
# curl -s 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
# # 4. Mount ConfigMaps in EasyHAProxy deployment
# # (See individual plugin examples for mount configuration)
# ```
#
# 5. Apply this manifest:
# kubectl apply -f plugins-combined.yml
# HOW TO START:
# ```bash
# 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
# HOW TO VERIFY IT'S WORKING:
# ```bash
# # Check all resources are created
# kubectl get deployment,service,ingress
#
# # Test public website (Cloudflare + path blocking)
# kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8080:80
# curl -H "Host: website.example.local" http://localhost:8080
# # Expected: 200 OK with "Public Website"
# curl -H "Host: website.example.local" http://localhost:8080/admin
# # Expected: HTTP 404 - Path blocked
#
# # Test protected API (JWT required)
# curl -H "Host: api.example.local" http://localhost:8080
# # Expected: HTTP 403 - Missing Authorization header
#
# # Test admin panel (IP whitelist)
# curl -H "Host: admin.example.local" http://localhost:8080
# # Expected: 200 OK from allowed IP, or HTTP 403 from blocked IP
# ```
#
# CLEAN UP:
# ```bash
# kubectl delete -f plugins-combined.yml
# ```
#
# ==============================================================================
---
# Public website service

54
examples/kubernetes/service.yml
View file

@ -1,3 +1,57 @@
# ==============================================================================
# EXAMPLE: Basic Kubernetes Ingress
# ==============================================================================
#
# WHAT THIS DEMONSTRATES:
# - Basic ingress configuration with EasyHAProxy
# - Multiple domains pointing to the same service
# - Complete deployment + service + ingress setup
# - HTTP ingress without TLS
#
# REQUIREMENTS (run these first):
# ```bash
# # 1. Ensure EasyHAProxy is installed in your cluster
# kubectl create namespace easyhaproxy
# kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
#
# # 2. Label the node where EasyHAProxy will run
# kubectl label nodes <node-name> "easyhaproxy/node=master"
#
# # 3. Add to /etc/hosts for local testing (idempotent)
# grep -q "example.org" /etc/hosts || echo "<node-ip> example.org www.example.org" | sudo tee -a /etc/hosts
# ```
#
# HOW TO START:
# ```bash
# kubectl apply -f service.yml
# ```
#
# HOW TO VERIFY IT'S WORKING:
# ```bash
# # Check resources are created
# kubectl get deployment,service,ingress container-example
#
# # Test via node IP
# curl -H "Host: example.org" http://<node-ip>:31080
# # Expected: 200 OK with "My Host Example"
#
# # Or use port-forward for testing
# kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8080:80
# curl -H "Host: example.org" http://localhost:8080
# # Expected: 200 OK with "My Host Example"
#
# # Test second domain
# curl -H "Host: www.example.org" http://<node-ip>:31080
# # Expected: Same response
# ```
#
# CLEAN UP:
# ```bash
# kubectl delete -f service.yml
# ```
#
# ==============================================================================
---
apiVersion: networking.k8s.io/v1
kind: Ingress

55
examples/kubernetes/service_tls.yml
View file

@ -1,3 +1,58 @@
# ==============================================================================
# EXAMPLE: TLS/SSL Kubernetes Ingress
# ==============================================================================
#
# WHAT THIS DEMONSTRATES:
# - HTTPS/TLS configuration with custom certificates
# - Kubernetes TLS secrets for SSL certificates
# - Complete deployment + service + secret + ingress with TLS
# - Using pre-generated test certificates
#
# REQUIREMENTS (run these first):
# ```bash
# # 1. Ensure EasyHAProxy is installed in your cluster
# kubectl create namespace easyhaproxy
# kubectl apply -f https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.6.0/deploy/kubernetes/easyhaproxy-daemonset.yml
#
# # 2. Label the node where EasyHAProxy will run
# kubectl label nodes <node-name> "easyhaproxy/node=master"
#
# # 3. Add to /etc/hosts for local testing (idempotent)
# grep -q "host2.local" /etc/hosts || echo "<node-ip> host2.local" | sudo tee -a /etc/hosts
#
# # Note: This example uses embedded test certificates
# # For production, create your own secret:
# # kubectl create secret tls host2-tls --cert=cert.crt --key=cert.key
# ```
#
# HOW TO START:
# ```bash
# kubectl apply -f service_tls.yml
# ```
#
# HOW TO VERIFY IT'S WORKING:
# ```bash
# # Check resources are created
# kubectl get deployment,service,ingress,secret tls-example
# kubectl get secret host2-tls
#
# # Test HTTPS (using port-forward)
# kubectl port-forward -n easyhaproxy deployment/easyhaproxy 8443:443
# curl -k -H "Host: host2.local" https://localhost:8443
# # Expected: 200 OK with "My Host Example"
#
# # Verify certificate
# openssl s_client -showcerts -connect localhost:8443 -servername host2.local < /dev/null
# # Expected: Certificate for host2.local
# ```
#
# CLEAN UP:
# ```bash
# kubectl delete -f service_tls.yml
# ```
#
# ==============================================================================
---
apiVersion: networking.k8s.io/v1
kind: Ingress