Skip to content

Commit 3e890f1

Browse files
AnadrisAnadris
committed
update documentation
1 parent dbb36c7 commit 3e890f1

File tree

12 files changed

+2308
-122
lines changed

12 files changed

+2308
-122
lines changed

‎README.md

Lines changed: 251 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,265 @@
1-
# BunkerWeb Kubernetes Helm chart
1+
# BunkerWeb Kubernetes Helm Chart
22

3-
Official [Helm chart](https://helm.sh/docs/) to deploy [BunkerWeb](https://www.bunkerweb.io/?utm_campaign=self&utm_source=github) on Kubernetes.
3+
![Version](https://img.shields.io/badge/version-1.0.2-blue)
4+
![AppVersion](https://img.shields.io/badge/app%20version-1.6.4-green)
5+
6+
Official [Helm chart](https://helm.sh/docs/) to deploy [BunkerWeb](https://www.bunkerweb.io/?utm_campaign=self&utm_source=github) on Kubernetes - A next-generation, open-source **web application firewall (WAF)** and reverse proxy.
7+
8+
## Features
9+
10+
- **Security First**: Advanced threat protection with automatic rule updates
11+
- **High Availability**: Support for DaemonSet and Deployment modes
12+
- **Monitoring**: Built-in Prometheus metrics and Grafana dashboards
13+
- **Management UI**: Web interface for configuration and monitoring
14+
- **Auto-scaling**: Kubernetes-native scaling capabilities
15+
- **Secret Management**: Integration with Kubernetes secrets
416

517
## Prerequisites
618

7-
Please first refer to the [BunkerWeb documentation](https://docs.bunkerweb.io/latest/?utm_campaign=self&utm_source=github), particularly the [Kubernetes integration](https://docs.bunkerweb.io/latest/integrations/?utm_campaign=self&utm_source=bunkerwebio#kubernetes) section.
19+
- Kubernetes 1.19+
20+
- Helm 3.8+
21+
- PV provisioner support in the underlying infrastructure (for persistence)
22+
23+
**Important**: Please first refer to the [BunkerWeb documentation](https://docs.bunkerweb.io/latest/?utm_campaign=self&utm_source=github), particularly the [Kubernetes integration](https://docs.bunkerweb.io/latest/integrations/?utm_campaign=self&utm_source=bunkerwebio#kubernetes) section.
24+
25+
## Installation
826

9-
## Helm repository
27+
### Add Helm Repository
1028

11-
The BunkerWeb Helm chart repository is available at `https://repo.bunkerweb.io/charts` :
1229
```bash
1330
helm repo add bunkerweb https://repo.bunkerweb.io/charts
31+
helm repo update
1432
```
1533

16-
You can then use the `bunkerweb` helm chart from that repository :
34+
### Install Chart
35+
1736
```bash
18-
helm install -f myvalues.yaml mybunkerweb bunkerweb/bunkerweb
37+
# Install with default values
38+
helm install mybunkerweb bunkerweb/bunkerweb
39+
40+
# Install with custom values
41+
helm install mybunkerweb bunkerweb/bunkerweb -f myvalues.yaml
42+
43+
# Install in specific namespace
44+
helm install mybunkerweb bunkerweb/bunkerweb -n bunkerweb --create-namespace
45+
```
46+
47+
> **Need help with configuration?** Check out our [Configuration Guide](docs/values.md) for detailed examples and best practices.
48+
49+
## Architecture Components
50+
51+
| Component | Description | Default State |
52+
|-----------|-------------|---------------|
53+
| **BunkerWeb** | Main WAF/reverse proxy | Required |
54+
| **Scheduler** | Configuration management | Required |
55+
| **Controller** | Kubernetes integration | Enabled |
56+
| **UI** | Web management interface | Enabled |
57+
| **MariaDB** | Database backend | Enabled |
58+
| **Redis** | Caching and persistence | Enabled |
59+
| **Prometheus** | Metrics collection | Disabled |
60+
| **Grafana** | Monitoring dashboards | Disabled |
61+
62+
## Configuration
63+
64+
For detailed configuration options, see our comprehensive documentation:
65+
66+
**[Values Guide](docs/values.md)** - Complete user guide
67+
**[Values Reference](docs/values-reference.md)** - Quick technical reference
68+
**[values.yaml](charts/bunkerweb/values.yaml)** - Source configuration file
69+
70+
### Security Settings
71+
72+
```yaml
73+
settings:
74+
misc:
75+
# Custom DNS resolvers
76+
dnsResolvers: "1.1.1.1 8.8.8.8"
77+
# API whitelist for internal access
78+
apiWhitelistIp: "127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16"
79+
```
80+
81+
### Kubernetes Integration
82+
83+
```yaml
84+
settings:
85+
kubernetes:
86+
# Namespaces to monitor (empty = all)
87+
namespaces: "default,production"
88+
# Custom ingress class
89+
ingressClass: "bunkerweb"
90+
# Cluster domain
91+
domainName: "cluster.local"
1992
```
2093
21-
## Values
94+
### High Availability Setup
95+
96+
```yaml
97+
bunkerweb:
98+
kind: DaemonSet # or "Deployment"
99+
replicas: 3 # Only for Deployment mode
100+
pdb:
101+
create: true
102+
minAvailable: 1
103+
104+
service:
105+
type: LoadBalancer
106+
externalTrafficPolicy: Local
107+
```
108+
109+
### Secret Management
110+
111+
```yaml
112+
settings:
113+
# Use existing secret for sensitive values
114+
existingSecret: "bunkerweb-secrets"
115+
# Or configure inline (less secure)
116+
ui:
117+
adminUsername: "admin"
118+
adminPassword: "secure-password"
119+
```
120+
121+
## Persistence
122+
123+
### Storage Requirements
124+
125+
| Component | Default Size | Purpose |
126+
|-----------|-------------|---------|
127+
| MariaDB | 5Gi | Configuration and logs |
128+
| Redis | 1Gi | Cache and banned IPs |
129+
| UI Logs | 5Gi | Access and error logs |
130+
| Prometheus | 8Gi | Metrics storage |
131+
| Grafana | 5Gi | Dashboards and config |
132+
133+
### Custom Storage Classes
134+
135+
```yaml
136+
mariadb:
137+
persistence:
138+
storageClass: "fast-ssd"
139+
size: 20Gi
140+
141+
redis:
142+
persistence:
143+
storageClass: "standard"
144+
size: 5Gi
145+
```
146+
147+
## Monitoring and Observability
148+
149+
### Enable Monitoring Stack
150+
151+
```yaml
152+
scheduler:
153+
proLicenceKey: your-bunkerweb-licence-key
154+
usePrometheusExporter: true
155+
156+
prometheus:
157+
enabled: true
158+
persistence:
159+
enabled: true
160+
size: 20Gi
161+
162+
grafana:
163+
enabled: true
164+
adminUser: admin
165+
adminPassword: "your-secure-password"
166+
ingress:
167+
enabled: true
168+
hosts:
169+
- host: grafana.example.com
170+
```
171+
172+
### Custom Dashboards
173+
174+
The chart includes pre-configured Grafana dashboards for:
175+
- BunkerWeb metrics and performance
176+
- Request analytics and threat detection
177+
- System health and resource usage
178+
179+
## Security Considerations
180+
181+
1. **Change Default Passwords**: Always set custom passwords for UI and database
182+
2. **Use Secrets**: Store sensitive data in Kubernetes secrets
183+
3. **Network Policies**: Enable network policies for production environments
184+
4. **Resource Limits**: Set appropriate CPU/memory limits
185+
5. **Pod Security**: Review and adjust security contexts
186+
187+
## Troubleshooting
188+
189+
### Common Issues
190+
191+
**BunkerWeb pods not starting:**
192+
```bash
193+
kubectl logs -l app.kubernetes.io/name=bunkerweb -n bunkerweb
194+
```
195+
196+
**Database connection issues:**
197+
```bash
198+
kubectl get pods -n bunkerweb
199+
kubectl describe pod mariadb-<pod-name> -n bunkerweb
200+
```
201+
202+
**Ingress not working:**
203+
```bash
204+
kubectl get ingress -n bunkerweb
205+
kubectl describe ingressclass bunkerweb
206+
```
207+
208+
### Health Checks
209+
210+
All components include health checks:
211+
- Liveness probes for automatic restart
212+
- Readiness probes for traffic routing
213+
- Custom healthcheck scripts
214+
215+
## Upgrading
216+
217+
```bash
218+
# Update repository
219+
helm repo update bunkerweb
220+
221+
# Check available versions
222+
helm search repo bunkerweb/bunkerweb --versions
223+
224+
# Upgrade to latest version
225+
helm upgrade mybunkerweb bunkerweb/bunkerweb
226+
227+
# Upgrade with new values
228+
helm upgrade mybunkerweb bunkerweb/bunkerweb -f new-values.yaml
229+
```
230+
231+
## Uninstallation
232+
233+
```bash
234+
# Uninstall release
235+
helm uninstall mybunkerweb -n bunkerweb
236+
237+
# Remove namespace (optional)
238+
kubectl delete namespace bunkerweb
239+
```
240+
241+
**Note**: PVCs are not automatically deleted and must be removed manually if needed.
242+
243+
244+
### Key Configuration Areas
245+
246+
- **Global Settings**: Common configuration across all components
247+
- **BunkerWeb**: Main reverse proxy configuration
248+
- **UI**: Web interface settings
249+
- **Database**: MariaDB configuration
250+
- **Monitoring**: Prometheus and Grafana setup
251+
- **Security**: Network policies and access control
252+
253+
### Quick Configuration Examples
254+
255+
See [`examples/`](examples/) directory for complete configuration examples.
256+
257+
## Support
258+
259+
- [Documentation](https://docs.bunkerweb.io/)
260+
- [GitHub Issues](https://github.com/bunkerity/bunkerweb/issues)
261+
- [Community Forum](https://github.com/bunkerity/bunkerweb/discussions)
262+
263+
## License
22264

23-
The full list of values are listed in the `charts/bunkerweb/values.yaml` file.
265+
This Helm chart is licensed under the same terms as BunkerWeb itself.

‎charts/bunkerweb/Chart.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ type: application
1515
# This is the chart version. This version number should be incremented each time you make changes
1616
# to the chart and its templates, including the app version.
1717
# Versions are expected to follow Semantic Versioning (https://semver.org/)
18-
version: 1.0.2
18+
version: 1.0.3
1919

2020
# This is the version number of the application being deployed. This version number should be
2121
# incremented each time you make changes to the application. Versions are not expected to

0 commit comments

Comments
 (0)