Skip to main content

Overview

Wazuh is an open-source security platform. Agents on your Linux, Windows and macOS hosts report to a Wazuh server, which detects intrusions and malware, watches file integrity, finds vulnerable packages and checks configuration against compliance benchmarks. Alerts are stored in the Wazuh indexer and explored in the Wazuh dashboard. This template deploys all three, with agents connecting from anywhere over a public TCP load balancer. Agents are the only ingestion path: the template has no syslog listener. To collect syslog from network devices, run an agent on the host that receives it. For general log search, see the related OpenSearch template.
This template deploys into an existing GVC that you already have. It does not create or manage a GVC. Install into a GVC with a single location: the template runs in one location.

What Gets Created

The manager creates a private certificate authority and the TLS certificates on first start. The CA key stays on the manager’s own volume.

Prerequisites

1

Create the credentials secret

One dictionary secret with exactly six keys must exist before you install:
Passwords are 8 to 64 characters, start with a letter, use only A-Z a-z 0-9 . * + ? -, and contain at least one upper-case letter, lower-case letter, digit and symbol. The Wz1. prefixes above satisfy that. Read the values back with cpln secret reveal SECRET_NAME -o yaml.Set credentialsSecretName to this name.
If the secret does not exist at install time, every workload waits and cpln logs shows nothing. The reason appears only in status.versions[].message of cpln workload get-deployments RELEASE_NAME-wazuh-manager --gvc GVC_NAME -o yaml.

Installation

Install the chart with the credentials secret name:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default is one node of each component. Set indexer.replicas: 3, manager.workers.replicas: 2 and dashboard.replicas: 2 for near-zero-downtime upgrades. Each component also takes an image and a resources block; keep all images on the same Wazuh version.

Credentials

Manager

Narrow allowedCidrs to the networks your agents connect from. Edits to ossec.conf made in the dashboard are reset on the next restart; put lasting changes in extraConfig. Custom rules, decoders and CDB lists made in the dashboard are kept. The manager volume holds every agent key and the CA key, so keep its snapshots on.

Workers

Workers keep agents connected while the manager restarts. With workers on, point agents at the worker load balancer; workers pass enrollment on to the manager, and the server API stays on the manager.

Indexer

Every volume set also takes an autoscaling block (enabled, maxCapacity, minFreePercentage, scalingFactor), off by default. Sizing is roughly 2 GiB per agent per 90 days.

Dashboard

Demo Agent

Connecting

Read the credentials with cpln secret reveal SECRET_NAME -o yaml. The dashboard’s status.canonicalEndpoint and the load balancer host are in each workload’s status:
The manager’s status.loadBalancer lists tcp://RELEASE_NAME-wazuh-manager-xxxx.yyyy.cpln.app:1514 and …:1515. To open a private dashboard (dashboard.publicAccess.enabled: false), forward it and browse to http://localhost:5601:

Enrolling an Agent

Install the agent on a host with the load balancer host name and the enrollment password, for example on Debian or Ubuntu after adding the Wazuh package repository:
The dashboard’s Deploy new agent page builds the same command for every operating system, with the host already filled in. The agent then appears under Endpoints.

Operations

Scaling and Availability

For near-zero-downtime upgrades and failover, set indexer.replicas: 3, manager.workers.replicas: 2 and dashboard.replicas: 2. With the single-node default, a restart of the manager or indexer pauses event processing; agents and the indexer shipper buffer and resend, so events are delayed, not lost. Grow indexer storage with indexer.volumeset.autoscaling. Scale the indexer up, never down: removing nodes can lose the data they hold.

Changing a Password

The secret is the source of truth on every start. Edit the key, then force a redeployment of the indexer, then the manager (and workers), then the dashboard. A password changed only in the dashboard reverts on the next restart.

Troubleshooting

The credentials secret is missing or misnamed. Read the reason from status.versions[].message:
Create the secret or correct credentialsSecretName; the workloads then start on their own.
That key’s password breaks the rules (8 to 64 characters, starts with a letter, only A-Z a-z 0-9 . * + ? -, one of each kind). Find the key in the logs, fix its value in the secret and force a redeployment of the workload:
The manager downloads about 1.7 GB of vulnerability content after the first install, which takes two hours or more. If the page is still empty after that, restart the manager once (Server management, Status, Restart).
The demo agent enrolls under a new name each time it restarts and can leave the old entry disconnected. Remove stale entries under Endpoints, and turn the demo agent off once your own agents connect.

Important Notes

  • Agent ports are open to the whole GVC while the load balancer is on. manager.internalAccess does not restrict ports 1514 and 1515 when manager.publicAccess.enabled is true; the enrollment password is the gate. It restricts them (and the API) once the load balancer is off.
  • manager.internalAccess.type cannot be none: the dashboard needs the API.
  • Custom rules in extraConfig. A <ruleset> block replaces the default one, so restate the default decoder_dir, rule_dir and list entries in it, or the default rules stop loading. Workers load rules synced from the master after a restart (PUT /cluster/restart).
  • Restarts can repeat alerts. Agents resend events the manager had not acknowledged, so an alert can appear twice after a restart. The Statistics page returns errors for about an hour after a manager start.
  • Access changes take time. After changing manager.publicAccess.* or dashboard.publicAccess.enabled, allow 30 seconds to about 10 minutes for the firewall and load balancer to apply.
  • Never replace the manager volume set. It holds every agent key and the CA key. If it is ever replaced, restart the indexer and dashboard so they pick up the new CA, and enroll the agents again.
  • Uninstalling deletes every volume set, with the stored alerts and every agent key; a final snapshot of each is kept for retentionDuration.
  • Disk. The indexer’s disk watermarks are off (as upstream ships it), so a full volume stops indexing. Keep the retention values set or turn on volume autoscaling.
  • Indexer node count must be 1 or an odd number of 3 or more.

External References