Skip to content

Commit e91b327

Browse files
author
Julie POUNY
committed
docs: add Otoroshi advanced features guide (WAF, reverse proxy, rate limiting, canary)
1 parent e468902 commit e91b327

1 file changed

Lines changed: 285 additions & 0 deletions

File tree

‎content/guides/otoroshi.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
---
2+
type: docs
3+
linkTitle: Otoroshi Advanced Features
4+
title: Otoroshi Advanced Features Guide
5+
description: Configure and use Otoroshi advanced features including WAF, Reverse Proxy, Rate Limiting, and Canary Deployments with detailed tutorials and best practices
6+
keywords:
7+
- otoroshi
8+
- api gateway
9+
- waf
10+
- reverse proxy
11+
- canary deployment
12+
- rate limiting
13+
- load balancing
14+
---
15+
16+
Otoroshi is a modern API Gateway that provides powerful features to secure, manage, and optimize your services.
17+
18+
This guide covers the main features tested and validated for deployment on Clever Cloud.
19+
20+
---
21+
22+
## WAF (Web Application Firewall)
23+
24+
Otoroshi integrates **Coraza**, an open-source WAF compatible with ModSecurity rules and compliant with OWASP recommendations. It filters and blocks malicious requests before they reach your applications.
25+
26+
### Configuration
27+
28+
#### Step 1: Create a WAF Item
29+
30+
1. Navigate to **Categories → WAF → WAF Config**
31+
2. Click **Add item**
32+
3. Add your security directives
33+
34+
#### Example Directives
35+
36+
```
37+
SecDefaultAction "phase:2,deny,status:403,log,auditlog"
38+
SecRule REMOTE_ADDR "@ip xxxxxxxxxxxxx" "id:1001,phase:1,deny,msg:'Blocking IP xxxxxxxxxxxxxxxxxxxxxx'"
39+
SecRule ARGS "@rx attack1" "phase:2,id:102,deny,status:403,log"
40+
41+
```
42+
43+
**Directive Explanations:**
44+
45+
- **SecDefaultAction**: Default action that blocks the request (`deny`), returns a 403 error, logs the event, and records the complete transaction in the audit module
46+
- **SecRule REMOTE_ADDR**: Rule applied in phase 1 (header analysis) that blocks a specific IP address
47+
- **SecRule ARGS**: Rule applied in phase 2 (GET/POST parameters analysis) that detects an attack pattern in arguments
48+
49+
#### Step 2: Create and Configure a Route
50+
51+
1. Navigate to **Shortcuts → Routes → Create new route**
52+
2. Configure the **Frontend** (public entry point):
53+
- Public URL used by your clients (set on Otoroshi addon)
54+
3. Configure the **Backend** (actual service):
55+
- Internal URL of your application that will process requests (set on your application)
56+
4. Add the **WAF** in the "Plugins" section
57+
58+
{{< callout type="info" >}}
59+
The frontend DNS must point to Otoroshi, not directly to your application. The backend URL is used by Otoroshi to proxy requests after applying WAF rules.
60+
{{< /callout >}}
61+
62+
---
63+
## Reverse Proxy
64+
65+
### Overview
66+
67+
Otoroshi natively supports multiple protocols:
68+
69+
- **HTTP/HTTPS**: Standard web requests
70+
- **TCP**: Raw TCP connections (databases, custom services)
71+
- **gRPC**: Modern RPC protocol based on HTTP/2
72+
73+
### Configuring a Simple Reverse Proxy
74+
75+
Otoroshi's versatile protocol support allows it to act as a reverse proxy for various types of services:
76+
77+
1. **Create a route** in Otoroshi
78+
2. **Configure the Frontend**:
79+
- Public hostname, port, and path (set on Otoroshi addon)
80+
3. **Configure the Backend**:
81+
- IP + port or URL of your actual service (set on your application)
82+
83+
Otoroshi intercepts incoming requests, applies your rules (security, rate limiting, etc.), and forwards them to the backend.
84+
85+
**Use Cases:**
86+
- Proxy HTTP/HTTPS requests to web applications
87+
- Forward TCP connections to databases or custom services
88+
- Route gRPC calls to microservices
89+
90+
### Frontend vs Backend
91+
92+
**Frontend**: The public entry point that clients use to access your service. This is the URL your users will call.
93+
94+
**Backend**: The actual internal address of your application/service that processes requests. Otoroshi proxies requests to this address after filtering through WAF and other plugins.
95+
96+
{{< callout type="info" >}}
97+
Your DNS must point the frontend domain to Otoroshi, not to your backend application. The backend URL is used internally by Otoroshi to forward filtered traffic.
98+
{{< /callout >}}
99+
100+
---
101+
102+
## Rate Limiting & Custom Quotas
103+
104+
### Overview
105+
106+
Rate limiting protects your services from abuse by controlling the number of requests allowed per time period. Otoroshi provides flexible quota management based on various criteria.
107+
108+
### Implementation
109+
110+
To limit the number of requests per IP or per user:
111+
112+
1. Navigate to your route's configuration
113+
2. Add the **"Custom quotas"** plugin in the "Plugins" section
114+
3. Configure the following parameters:
115+
- **Quota**: Number of authorized requests
116+
- **Period**: Time window (per second, minute, hour, day)
117+
- **Criteria**: IP address, API key, user, etc.
118+
119+
**Common Use Cases:**
120+
- Protect your APIs against abuse and brute force attacks
121+
- Manage differentiated quotas for commercial tiers
122+
- Mitigate DDoS attempts
123+
- Implement fair usage policies (free vs paid tiers)
124+
125+
### Configuration Example
126+
127+
```json
128+
{
129+
"throttling_quota": "1000",
130+
"throttling_period": "3600",
131+
"throttling_by": "ip"
132+
}
133+
```
134+
135+
This configuration allows **1000 requests per hour per IP address**.
136+
137+
### Additional Options
138+
139+
You can customize rate limiting based on:
140+
- **IP address**: Limit per visitor
141+
- **API key**: Different quotas per client
142+
- **User**: Authenticated user limits
143+
- **Custom header**: Advanced filtering
144+
145+
---
146+
147+
## Canary Deployments
148+
149+
Canary mode allows you to test a new version of your application on a percentage of traffic before a complete deployment. This technique reduces risk by gradually exposing new code to production users.
150+
151+
### Method 1: Route-Level Configuration with Plugin (Recommended)
152+
153+
This method provides more granular control and is easier to configure for single routes.
154+
155+
#### Configuration Steps
156+
157+
1. **Create a new route**
158+
2. **Select the "Canary Mode" plugin**
159+
3. **Configure the following parameters**:
160+
- **Frontend**: Public URL (set on Otoroshi addon)
161+
- **Canary mode**:
162+
- **Traffic**: 0.2 for 20% redirection to canary (or 0.5 for 50%)
163+
- **Targets**:
164+
- Hostname: `app-canary.cleverapps.io`
165+
- Port: `443`
166+
- Weight: `1`
167+
- **Backend**: Stable application URL (e.g., `app-stable.cleverapps.io`)
168+
169+
#### Complete Test Script
170+
171+
```sh
172+
#!/bin/bash
173+
174+
echo "=== Otoroshi Canary Mode Test ==="
175+
echo "Date: $(date)"
176+
echo ""
177+
178+
STABLE=0
179+
CANARY=0
180+
UNKNOWN=0
181+
182+
# Replace with your actual Otoroshi frontend URL
183+
FRONTEND_URL="http://myapp.mydomain.com"
184+
185+
for i in {1..100}; do
186+
RESPONSE=$(curl -L -s "$FRONTEND_URL")
187+
188+
if echo "$RESPONSE" | grep -q "STABLE"; then
189+
((STABLE++))
190+
elif echo "$RESPONSE" | grep -q "CANARY"; then
191+
((CANARY++))
192+
else
193+
((UNKNOWN++))
194+
fi
195+
196+
echo -n "."
197+
done
198+
199+
echo ""
200+
echo ""
201+
echo "Results over 100 requests:"
202+
echo " → Stable: $STABLE"
203+
echo " → Canary: $CANARY"
204+
echo " → Unknown: $UNKNOWN"
205+
echo ""
206+
207+
PERCENT_CANARY=$((CANARY))
208+
echo "Canary rate: ${PERCENT_CANARY}%"
209+
```
210+
211+
#### Expected Results
212+
213+
- Traffic at **0.2** (20%): ~20% to CANARY, ~80% to STABLE
214+
- Traffic at **0.5** (50%): ~50% to CANARY, ~50% to STABLE
215+
216+
{{< callout type="warning" >}}
217+
Always monitor error rates and latency when testing canary deployments. Start with a low percentage (5-10%) and gradually increase if metrics remain healthy.
218+
{{< /callout >}}
219+
220+
---
221+
222+
### Method 2: Service-Level Configuration
223+
224+
This method is useful for managing multiple routes with the same canary configuration.
225+
226+
#### Configuration Steps
227+
228+
1. **Create a new Service**:
229+
```
230+
Name: "My Service"
231+
Description: "Service with Canary"
232+
```
233+
234+
2. **Service Exposition Settings**:
235+
```
236+
Exposed domain: myapp.mydomain.com
237+
Legacy domain: true
238+
Strip path: true
239+
```
240+
241+
3. **Service Targets**:
242+
```
243+
Load balancing: WeightBestResponseTime
244+
Weight ratio: 0.2
245+
246+
Target 1: app-stable.cleverapps.io (STABLE)
247+
Target 2: app-canary.cleverapps.io (CANARY)
248+
```
249+
250+
4. **URL Patterns**:
251+
```
252+
Public patterns: "/.*"
253+
```
254+
255+
#### Testing
256+
257+
```sh
258+
# Replace with your actual frontend URL
259+
out=$(for i in {1..200}; do curl -s https://myapp.mydomain.com | grep Version; done);
260+
echo "CANARY: $(echo "$out" | grep -c CANARY)"
261+
echo "STABLE: $(echo "$out" | grep -c STABLE)"
262+
```
263+
264+
Expected Result: ~40 requests to CANARY, ~160 to STABLE (20/80 ratio)
265+
{{< callout type=“info” >}}
266+
Traffic Flow: Client → your-domain.com → Otoroshi → { stable / canary }
267+
{{< /callout >}}
268+
269+
### Load Balancing Strategies
270+
271+
When using canary deployments, you can choose from several load balancing algorithms:
272+
- WeightBestResponseTime: Routes traffic based on response time and weights
273+
- RoundRobin: Distributes requests evenly across targets
274+
- Random: Randomly selects a target for each request
275+
- IpAddressHash: Routes based on client IP (sticky sessions)
276+
277+
---
278+
## Resources
279+
280+
- Official Otoroshi Documentation : https://maif.github.io/otoroshi/
281+
- Clever Cloud Documentation : https://www.clever.cloud/developers/doc/
282+
- OWASP ModSecurity Core Rule Set : https://owasp.org/www-project-modsecurity-core-rule-set/
283+
- Coraza WAF Documentation : https://coraza.io/
284+
- API Gateway Patterns : https://microservices.io/patterns/apigateway.html
285+

0 commit comments

Comments
 (0)