Getting started

Upstream package is used by default

The debops.filebeat role depends on the debops.extrepo Ansible role to configure access to the Elastic.co APT repository. This means that usually the latest available Filebeat release will be installed by default. If you require older releases, you can use the debops.apt_preferences role to select the desired package version.

Alternatively, you can "mask" the filebeat__extrepo__dependent_sources variable in the Ansible inventory and configure the APT repositories yourself via the debops.apt role.

Default configuration

The filebeat role includes a basic configuration for Filebeat which will by default enable inputs for /var/log/*.log files, as well as the system module. Several other Filebeat modules and input log configurations will be enabled conditionally, based on the presence of various Ansible local facts.

The role will also configure Filebeat to read input configuration from the /etc/filebeat/inputs.d/ directory, where other applications can add their own configuration. The directory will not be created by default unless configuration snippets placed in it are configured or enabled conditionally.

The default output is directed at an Elasticsearch database installed on the same host as Filebeat. To change it, you can define in the Ansible inventory:

filebeat__configuration:

  - name: 'output_elasticsearch'
    config:
      output.elasticsearch:
        hosts: [ 'elasticsearch.example.org:9200' ]

See the filebeat__configuration documentation for more details. Elasticsearch database can be installed using the debops.elasticsearch role.

Check the Filebeat configuration upstream documentation to learn more about configuring Filebeat for your environment and requirements.

Role debugging tips

Most of the configuration files generated by the role are protected by the Ansible no_log keyword. To make debugging easier, you can use the debops__no_log variable in an inventory (in the development environment) or with Ansible --extra-vars parameter (one time, for production environment) to disable log protection. See the variable documentation for more details.

Example inventory

To install and configure Filebeat on a host, it needs to be included in the [debops_service_filebeat] Ansible inventory group:

[debops_all_hosts]
hostname

[debops_service_filebeat]
hostname

Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.filebeat role:

---

- name: Manage Filebeat service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_filebeat' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: extrepo
      tags: [ 'role::extrepo', 'skip::extrepo', 'role::filebeat' ]
      extrepo__dependent_sources:
        - '{{ filebeat__extrepo__dependent_sources }}'

    - role: filebeat
      tags: [ 'role::filebeat', 'skip::filebeat' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

role::filebeat

Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.