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 thecombine
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. ifabsent
, the configuration will not be included in the final file. Ifignore
, 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. Thename
parameter is also used as an identifier, entries with the samename
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 thefilebeat.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. Ifabsent
, the configuration file will not be generated, and an existing file will be removed. Ifignore
, 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 confidental 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. Ifabsent
, the key will be removed from the keystore.force
Optional, boolean. If present and
True
, the specified key will be updated in the keystore.