wazuh-operator

README

Wazuh Kubernetes Operator

A Kubernetes operator for managing Wazuh clusters, providing a declarative way to deploy and configure Wazuh security monitoring platforms.

Features

• Declarative Cluster Management - Define your entire Wazuh cluster using Kubernetes custom resources
• Automated Deployment - Automatically provisions Manager, Indexer, and Dashboard components
• Rule & Decoder Management - Manage Wazuh detection rules and log decoders as CRDs
• CDB Lists & Active Response - Manage CDB lists and custom active response scripts declaratively
• Integrations & Agent Groups - Configure external integrations (Slack, VirusTotal, …) and shared agent group configuration declaratively
• OpenSearch Security CRDs - Manage users, roles, role mappings, and tenants declaratively
• Wazuh API RBAC CRDs - Manage Manager API roles, policies, rules, and users; restrict dashboard menus per user via run_as
• Index Lifecycle Management - Configure ISM policies, index templates, and snapshot policies
• Backup & Restore - OpenSearch snapshots and Wazuh Manager backups to S3, GCS, Azure, HDFS
• TLS Automation - Auto-generated certificates with hot reload support (Wazuh 4.9+)
• High Availability - Multi-node deployments with pod disruption budgets
• Safe Rollouts - Controlled indexer/manager drain with retry and rollback
• Networking - Gateway API and Ingress for dashboard/manager exposure
• Storage Ops - Online PVC volume expansion and log rotation
• Monitoring & Tracing - Prometheus metrics, ServiceMonitor, and OpenTelemetry distributed tracing

Architecture

The operator watches resources.wazuh.com custom resources and reconciles the Wazuh stack: it deploys and configures the Manager, Indexer, and Dashboard, and pushes RBAC / rules / index config to their APIs.

graph LR
    crs["Custom Resources<br/>WazuhCluster, Wazuh*, OpenSearch*"]
    operator["Wazuh Operator<br/>(controllers)"]
    crs -->|watch / reconcile| operator

    agents["Wazuh agents"]

    subgraph cluster["WazuhCluster (managed)"]
        manager["Manager<br/>Master + Workers"]
        indexer["Indexer<br/>(modified OpenSearch)"]
        dashboard["Dashboard<br/>(modified OpenSearch Dashboards)"]
    end

    operator -->|deploy + configure| manager
    operator -->|deploy + configure| indexer
    operator -->|deploy + configure| dashboard

    agents -->|events| manager
    manager -->|alerts via Filebeat| indexer
    dashboard -->|query / search| indexer
    dashboard -->|Manager API :55000| manager

Quick Start

Prerequisites

• Kubernetes 1.25+
• kubectl configured
• 16GB+ RAM recommended

Installation with Helm

Due to CRD size, use helm template + kubectl apply instead of helm install:

# Install the operator
helm template wazuh-operator oci://ghcr.io/maximewewer/charts/wazuh-operator \
  --namespace wazuh-operator --create-namespace | kubectl apply -f -

# Deploy a Wazuh cluster
helm template wazuh-cluster oci://ghcr.io/maximewewer/charts/wazuh-cluster \
  --namespace wazuh | kubectl apply -f -

# Check status
kubectl get wazuhcluster -n wazuh

Access Dashboard

kubectl port-forward svc/wazuh-cluster-dashboard -n wazuh 5601:5601

Open https://localhost:5601 - Credentials are auto-generated in secrets.

See Quick Start Guide for detailed instructions.

Supported Wazuh Versions

Wazuh	OpenSearch	Notes
4.12.x - 4.14.x	2.19.0+	Automatic TLS certificate hot reload (file-watch).
4.10.x - 4.11.x	2.16.0
4.9.x	2.13.0	TLS certificate hot reload via API call. Minimum version supported by the operator.
< 4.9.0	Not supported	Might work, but it hasn't been tested.

Custom Resource Definitions

API Group: resources.wazuh.com/v1

Category	CRDs	Short Names
Wazuh Core	WazuhCluster	wc
Wazuh Config	WazuhRule, WazuhDecoder, WazuhIntegration, WazuhCDBList, WazuhActiveResponse, WazuhCertificate, WazuhFilebeat, WazuhAgentGroup, WazuhAgentGroupAssignment	wrule, wdecoder, wintegration, wcdb, war, wzcert, wfb, wagentgroup, waga
Wazuh API RBAC	WazuhRole, WazuhUser	wrole, wuser
Wazuh Backup	WazuhBackup, WazuhRestore	wbak, wrest
OpenSearch Security	OpenSearchUser, OpenSearchRole, OpenSearchRoleMapping, OpenSearchActionGroup, OpenSearchTenant, OpenSearchAuthConfig	osuser, osrole, osrmap, osag, ostenant, osauth
OpenSearch Index	OpenSearchIndex, OpenSearchIndexTemplate, OpenSearchComponentTemplate, OpenSearchISMPolicy, OpenSearchSnapshotPolicy	osidx, osidxt, osctpl, osism, ossnap
OpenSearch Backup	OpenSearchSnapshotRepository, OpenSearchSnapshot, OpenSearchRestore	osrepo, ossnapshot, osrestore

See CRD Reference for complete API documentation.

Documentation

User Guide

Topic	Description
Installation	How to install the operator
Quick Start	Deploy your first cluster
Credentials	Auto-generated passwords, secrets
TLS Configuration	Certificate management
Wazuh API RBAC	Manager API roles/users, run_as restriction
Monitoring	Prometheus integration
Backup & Restore	Data protection (S3, GCS, Azure, HDFS)
Repository Plugins	Auto plugin install & keystore
OpenSearch Security	Indexer users, roles, tenants
Gateway API & Ingress	Expose dashboard/manager
Drain Strategy	Safe node drain, retry, rollback
Log Rotation	Component log rotation
Volume Expansion	Online PVC growth
Filebeat	Manager→indexer shipping config
Advanced Topology	NodePools, dedicated roles
Sizing	Resource sizing guidance
Examples	Configuration examples
Troubleshooting	Common issues and debugging

Developer Guide

Topic	Description
Architecture	Overall design
Testing Guide	How to run and write tests
Contributing	How to contribute

Development

# Generate manifests and code
make manifests generate

# Build and test
make build test

# Build Docker image
make docker-build IMG=myregistry/wazuh-operator:dev

# Run locally
make install run

See Testing Guide for complete testing instructions.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

• GitHub Issues
• Wazuh Documentation

Acknowledgments

• Built with Kubebuilder
• Inspired by opensearch-k8s-operator
• Based on Wazuh security platform