Default variable details

Some of the debops.filebeat default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

filebeat__configuration

The filebeat__*_configuration variables define the contents of the /etc/filebeat/filebeat.yml configuration file. Each variable contains a list of YAML dictionaries; each dictionary defines a part of the configuration which gets merged together during Ansible execution.

You can read the Filebeat configuration documentation to learn more about configuring Filebeat itself.

Examples

Extend the default list of Filebeat inputs to include logs from Docker containers (the configuration sections are not merged, but override each other in order of appearance):

filebeat__configuration:

  - name: 'filebeat_inputs'
    config:
      filebeat.inputs:
        - type: 'log'
          enabled: True
          paths:
            - '/var/log/*.log'
            - '/var/log/messages'
        - type: 'container'
          paths:
            - '/var/lib/docker/containers/*/*.log'

Configure Filebeat to output its data to Elasticsearch on another host:

filebeat__configuration:

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

Configure Elasticsearch output, but over an encrypted connection (requires X-Pack support) using certificates managed by the debops.pki role. The access to the cluster is protected by a password, stored in the Filebeat keystore:

filebeat__configuration:

  - name: 'output_elasticsearch'
    config:
      output.elasticsearch:
        hosts:
          - 'https://elasticsearch.example.org:9200'
        ssl:
          certificate_authorities: '/etc/pki/realms/domain/CA.crt'
          certificate: '/etc/pki/realms/domain/default.crt'
          key: '/etc/pki/realms/domain/default.key'
        password: '${ELASTIC_PASSWORD}'

The filebeat__original_configuration variable contains the configuration that comes with the filebeat APT package re-implemented for consumption by the role. The filebeat__default_configuration variable contains some additional configuration enabled by default.

Syntax

Each configuration entry is a YAML dictionary with specific parameters:

name

Required. An identifier for a particular configuration entry, not used otherwise. The configuration entries with the same name parameter override each other.

config

Required. A dictionary which holds the Filebeat configuration written in YAML. The config values from different configuration entries are merged recursively using the combine Ansible filter into a final YAML document.

YAML keys can be specified in a tree-like structure:

output:
  elasticsearch:
    hosts:
      - 'elasticsearch.example.org:9200'

Or, they can be defined on a single line, separated by dots:

output.elasticsearch.hosts: [ 'elasticsearch.example.org:9200' ]

The combine Ansible filter does not automatically expand the dot-notation to a tree-like structure. Therefore it's important to use the same style thruought the configuration, otherwise the final YAML document will have duplicate entries.

state

Optional. If not specified or present, the configuration will be included in the generated /etc/filebeat/filebeat.yml configuration file. if absent, the configuration will not be included in the final file. If ignore, the entry will not be evaluated by Ansible during execution.

filebeat__snippets

The filebeat__*_snippets variables define the placement and contents of various *.yml files under the /etc/filebeat/ directory. The files can include Filebeat configuration in YAML format.

Examples

Define an input source for logs generated by a custom application:

filebeat__snippets:

  - name: 'inputs.d/application.yml'
    config:
      type: 'log'
      enabled: True
      paths: [ '/var/log/application/*.log' ]

Add configuration for a built-in Filebeat module:

filebeat__snippets:

  - name: 'modules.d/auditd.yml'
    config:
      - module: 'auditd'
        log:
          enabled: True

You can find more example configurations in the filebeat__default_snippets variable.

Syntax

Each configuration entry is a YAML dictionary with specific parameters:

name

Required. Path of the configuration file, relative to the /etc/filebeat/ directory, with all needed subdirectories. The name parameter is also used as an identifier, entries with the same name parameter override each other in order of appearance.

Role by default configures two subdirectories for input (input.d/) and Filebeat modules (modules.d/) configuration. Don't use the filebeat.yml as the filename, otherwise you will override the main configuration file.

config

Required. A dictionary which holds the Filebeat configuration written in YAML. The value can either be a dictionary or a list of dictionaries, the result in the generated file will always be a list.

state

Optional. If not specified or present, the configuration file will be generated. If absent, the configuration file will not be generated, and an existing file will be removed. If ignore, the entry will not be evaluated by Ansible during execution.

comment

Optional. Comment to be included at the top of the generated file.

mode

Optional. Specify the filesystem permissions of the generated file. If not specified, 0600 will be used by default.

filebeat__keys

The filebeat__*_keys variables define the contents of the Filebeat keystore used to keep confidential data like passwords or access tokens. The keys can be referenced in the Filebeat configuration files using the ${secret_key} syntax.

Examples

Add an Elasticsearch password used for access over a secure connection. The password is retrieved from the secret/ directory on the Ansible Controller, managed by the debops.secret Ansible role:

filebeat__keys:

  - ELASTIC_PASSWORD: '{{ lookup("file", secret + "/elastic-stack/elastic/password") }}'
  - KIBANA_PASSWORD:  '{{ lookup("file", secret + "/elastic-stack/kibana/password") }}'

Update an existing key with new content (presence of the force parameter will update the key on each Ansible run):

filebeat__keys:

  - name: 'ELASTIC_PASSWORD'
    value: 'new-elasticsearch-password'
    force: True

Remove a key from the Filebeat keystore:

filebeat__keys:

  - name: 'ELASTIC_PASSWORD'
    state: 'absent'

Syntax

Each key entry is defined by a YAML dictionary. The keys can be defined using a simple format, with dictionary key being the secret key name, and its value being the secret value. In this case you should avoid the name or value as the secret keys.

Alternatively, secret keys can be defined using YAML dictionaries with specific parameters:

name: Required. Name of the secret key to store in the Filebeat keystore.
value: Optional. A string with the value which should be stored under a given key.
state: Optional. If not specified or present, the key will be inserted into the keystore. If absent, the key will be removed from the keystore.
force: Optional, boolean. If present and True, the specified key will be updated in the keystore.