BunkerWeb Kubernetes Helm Chart

July 17, 2026 · View on GitHub

Official Helm chart to deploy BunkerWeb on Kubernetes - A next-generation, open-source web application firewall (WAF) and reverse proxy.

Features

Security First: Advanced threat protection with automatic rule updates
High Availability: Support for DaemonSet and Deployment modes
Monitoring: Built-in Prometheus metrics and Grafana dashboards
Management UI: Web interface for configuration and monitoring
AI Integration: MCP server for AI assistants (Claude Code, etc.)
Auto-scaling: Kubernetes-native scaling capabilities
Secret Management: Integration with Kubernetes secrets

Prerequisites

Kubernetes 1.19+
Helm 3.8+
PV provisioner support in the underlying infrastructure (for persistence)
Kubernetes Gateway API CRDs installed (required for Gateway API support, see the Gateway API install guide)

Important: Please first refer to the BunkerWeb documentation, particularly the Kubernetes integration section.

Installation

Add Helm Repository

helm repo add bunkerweb https://repo.bunkerweb.io/charts
helm repo update

Install Chart

# Install with default values
helm install mybunkerweb bunkerweb/bunkerweb

# Install with custom values
helm install mybunkerweb bunkerweb/bunkerweb -f myvalues.yaml

# Install in specific namespace
helm install mybunkerweb bunkerweb/bunkerweb -n bunkerweb --create-namespace

Need help with configuration? Check out our Configuration Guide for detailed examples and best practices.

Architecture Components

Component	Description	Default State
BunkerWeb	Main WAF/reverse proxy	Required
Scheduler	Configuration management	Required
Controller	Kubernetes integration	Enabled
UI	Web management interface	Enabled
API	External REST API for automation	Enabled
MCP	Model Context Protocol server for AI assistants	Enabled
MariaDB	Database backend	Enabled
Redis	Caching and persistence	Enabled
Prometheus	Metrics collection	Disabled
Grafana	Monitoring dashboards	Disabled

Configuration

For detailed configuration options, see our comprehensive documentation:

Values Guide - Complete user guide
Values Reference - Quick technical reference
values.yaml - Source configuration file

Controller selection: The controller runs as either a GatewayController or an IngressController, never both. If both are configured, GatewayController takes priority.

Configuration Topics

Topic	Example	Reference
Security settings	`examples/all-in-one.yaml`	docs/values.md#settings
Kubernetes integration	`examples/all-in-one.yaml`	docs/values.md#settings
High availability	`examples/high-availability.yaml`	docs/values.md#bunkerweb, #service
MCP server	`examples/mcp-integration.yaml`	docs/values.md#mcp
Secret management	`examples/bunkerweb-secret.yaml`	docs/values.md#settings
Persistence	`examples/high-availability.yaml`	docs/values.md#mariadb, #redis, #grafana, #prometheus, #ui
Monitoring	`examples/all-in-one.yaml`	docs/values.md#prometheus, #grafana

Security note: The MCP server has no built-in authentication for the /mcp endpoint. Always use IP whitelisting or network policies to restrict access.

Monitoring and Observability

Custom Dashboards

The chart includes pre-configured Grafana dashboards for:

BunkerWeb metrics and performance
Request analytics and threat detection
System health and resource usage

Security Considerations

Change Default Passwords: Always set custom passwords for UI and database
Use Secrets: Store sensitive data in Kubernetes secrets
Network Policies: Enable network policies for production environments
Resource Limits: Set appropriate CPU/memory limits
Pod Security: Review and adjust security contexts
MCP Access Control: Always configure IP whitelisting when exposing the MCP server

Troubleshooting

Common Issues

BunkerWeb pods not starting:

kubectl logs -l app.kubernetes.io/name=bunkerweb -n bunkerweb

Database connection issues:

kubectl get pods -n bunkerweb
kubectl describe pod mariadb-<pod-name> -n bunkerweb

Ingress not working:

kubectl get ingress -n bunkerweb
kubectl describe ingressclass bunkerweb

Health Checks

All components include health checks:

Liveness probes for automatic restart
Readiness probes for traffic routing
Custom healthcheck scripts

Upgrading

# Update repository
helm repo update bunkerweb

# Check available versions
helm search repo bunkerweb/bunkerweb --versions

# Upgrade to latest version
helm upgrade mybunkerweb bunkerweb/bunkerweb

# Upgrade with new values
helm upgrade mybunkerweb bunkerweb/bunkerweb -f new-values.yaml

Version-specific notes

> 1.0.24: When settings.existingSecret is set, the BunkerWeb Pro license should be provided via the secret's pro-license-key key (a plain scheduler.proLicenseKey value is ignored). The same now applies to the optional feature secrets (zerossl-api-key, custom-ssl-key, sessions-secret, auth-basic-password, darkvisitors-token, crowdsec-api-key).
- Upgrade note: these secret keys are optional, and when settings.existingSecret is set it takes precedence over the matching plaintext values (scheduler.features.sessions.sessionsSecret, scheduler.features.authBasic.authBasicPassword, etc.). If you previously combined settings.existingSecret (for the database/Redis) with plaintext feature values, those plaintext values are now ignored — add the corresponding keys to your existing secret, or the feature will lose its credential silently.

Uninstallation

# Uninstall release
helm uninstall mybunkerweb -n bunkerweb

# Remove namespace (optional)
kubectl delete namespace bunkerweb

Note: PVCs are not automatically deleted and must be removed manually if needed.

Key Configuration Areas

Global Settings: Common configuration across all components
BunkerWeb: Main reverse proxy configuration
UI: Web interface settings
API: External REST API for automation and integrations
MCP: AI assistant integration (Claude Code, etc.)
Database: MariaDB configuration
Monitoring: Prometheus and Grafana setup
Security: Network policies and access control

Quick Configuration Examples

See examples/ directory for complete configuration examples.

Support

License

This Helm chart is licensed under the same terms as BunkerWeb itself.