How to enable Filebeat load balancing for Elasticsearch output

Sending every event to a single Elasticsearch node concentrates ingest pressure on one HTTP endpoint, one network path, and one maintenance window. Spreading Filebeat publish traffic across multiple cluster nodes keeps log delivery moving during node restarts and reduces hot spots when several systems ship at once.

The output.elasticsearch backend opens HTTP publishing connections to the hosts listed in /etc/filebeat/filebeat.yml and sends events with the Elasticsearch Bulk API. loadbalance makes Filebeat publish through all configured hosts instead of choosing one active host, and worker controls how many publishing connections Filebeat creates per host.

All configured endpoints must belong to the same Elasticsearch cluster and use the same authentication, proxy, and TLS settings. Packaged Linux installations normally keep the main config at /etc/filebeat/filebeat.yml and run the filebeat systemd service; setting loadbalance explicitly keeps the intended behavior visible even though Elastic documents it as enabled by default.

1. Open the Filebeat configuration file.

   $ sudo nano /etc/filebeat/filebeat.yml

   YAML indentation is significant; keep nested keys aligned and use spaces instead of tabs.

2. Configure multiple Elasticsearch hosts in the output.elasticsearch block.

   output.elasticsearch:
     hosts:
       - "http://node-01.example.net:9200"
       - "http://node-02.example.net:9200"
     loadbalance: true
     worker: 2

   Only one output.* block can be enabled at a time. Keep existing username, password, api_key, proxy_*, and ssl.* settings in the same output.elasticsearch block so every connection uses identical transport and authentication settings.

3. Keep the total publishing connection count conservative when raising worker.

   worker: 2 with two hosts creates four publishing connections. Use a conservative value unless the cluster and network are sized for the extra parallelism.

4. Set preset to custom when the output block already uses a performance preset.

   Filebeat performance presets can override manual output tuning. Elastic also accepts workers as an alias for worker, but one spelling keeps the saved config easier to review.

5. Test the configuration for syntax errors.

   $ sudo filebeat test config -c /etc/filebeat/filebeat.yml
   Config OK

   A scratch config that contains only output.elasticsearch fails because Filebeat also expects at least one enabled input or module.
   Related: How to test a Filebeat configuration

6. Test the Elasticsearch output connections from the saved configuration.

   $ sudo filebeat test output -c /etc/filebeat/filebeat.yml
   elasticsearch: http://node-01.example.net:9200...
     parse url... OK
     connection...
       parse host... OK
       dns lookup... OK
       addresses: 192.0.2.11
       dial up... OK
     TLS... WARN secure connection disabled
     talk to server... OK
     version: 9.4.2
   elasticsearch: http://node-01.example.net:9200...
     parse url... OK
     connection...
       parse host... OK
       dns lookup... OK
       addresses: 192.0.2.11
       dial up... OK
     TLS... WARN secure connection disabled
     talk to server... OK
     version: 9.4.2
   elasticsearch: http://node-02.example.net:9200...
     parse url... OK
     connection...
       parse host... OK
       dns lookup... OK
       addresses: 192.0.2.12
       dial up... OK
     TLS... WARN secure connection disabled
     talk to server... OK
     version: 9.4.2
   elasticsearch: http://node-02.example.net:9200...
     parse url... OK
     connection...
       parse host... OK
       dns lookup... OK
       addresses: 192.0.2.12
       dial up... OK
     TLS... WARN secure connection disabled
     talk to server... OK
     version: 9.4.2

   With worker: 2, Filebeat repeats each host in the output test once per worker connection.
   Related: How to test Filebeat output connectivity

7. Restart the Filebeat service to apply the updated output settings.

   $ sudo systemctl restart filebeat

   Related: How to manage the Filebeat service with systemctl in Linux

8. Confirm the service returned to an active state.

   $ sudo systemctl is-active filebeat
   active

   If the command returns failed or inactive, inspect the full service status and journal output before retrying the restart.
   Related: How to manage the Filebeat service with systemctl in Linux

9. Review recent Filebeat logs for connections to both Elasticsearch hosts.

   $ sudo journalctl --unit=filebeat --no-pager --grep 'elasticsearch url' --since '5 minutes ago'
   Jun 18 12:02:23 loghost01 filebeat[26575]: {"log.level":"info","@timestamp":"2026-06-18T12:02:23.428Z","log.logger":"elasticsearch.esclientleg","message":"elasticsearch url: http://node-01.example.net:9200","service.name":"filebeat","ecs.version":"1.6.0"}
   Jun 18 12:02:23 loghost01 filebeat[26575]: {"log.level":"info","@timestamp":"2026-06-18T12:02:23.431Z","log.logger":"elasticsearch.esclientleg","message":"elasticsearch url: http://node-02.example.net:9200","service.name":"filebeat","ecs.version":"1.6.0"}

   With multiple workers, duplicate connection lines for the same host are expected because Filebeat logs one line per connection.