ARCHIVED

This project is not being maintained anymore. If you want to get started, here are some alternatives:

• Start a free trial on Elastic Cloud, our service hosted online.
• Check out Elastic Cloud on Kubernetes (ECK) for deploying the stack using Kubernetes.
• Review our guide on Running the Elastic Stack on Docker.
• Explore the Elastic Stack Terraform provider.

ansible-beats

This role helps you install Beats that are supported by Elastic.

Tested Beats

• Filebeat
• MetricBeat (previously known as TopBeat in version 1.x)
• Packetbeat

Tested Versions

• 7.x
• 6.x

Tested Platforms

• Ubuntu 16.04
• Ubuntu 18.04
• Ubuntu 20.04
• Debian 8
• Debian 9
• Debian 10
• CentOS 7
• Amazon Linux 2

Usage

To use this, create your Ansible playbook with the tasks you want, and include the beats role. Make sure you have access to this repository in your playbook.

ansible-galaxy install elastic.beats,v7.17.0

Next, create a playbook in YAML format that includes the beats role. Applying this role will install Filebeat on a host.

Here's a simple example configuration:

  hosts: localhost
  roles:
    - role: elastic.beats
  vars:
    beats_version: 7.17.0
    beat: filebeat
    beat_conf:
      filebeat:
        inputs:
          - type: log
            enabled: true
            paths:
              - /var/log/*.log

The above example installs Filebeat version 7.17.0 on the host 'localhost'.

Notes:

• You can check the default Beats version in beats_version and change it in your playbook if you need a different version.
• While this role has been tested with one version each of 7.x and 6.x, it should usually work with other versions too.
• The beat variable specifies which Beat product to install. Currently tested Beats include Filebeat, Metricbeat, and Packetbeat, but it should work with other Beats from The Beats Family as well.

Testing

This playbook uses Kitchen for continuous integration and local testing.

Requirements

• Ruby
• Bundler
• Docker
• Make

Running the tests

To set up an Ubuntu 18.04 host:

$ make converge

To run the tests:

$ make verify

To see a list of all test suites:

$ make list

The default test suite is Ubuntu 18.04. You can test other suites by changing the PATTERN variable:

$ make converge PATTERN=standard-centos-7

To run all tests for CentOS:

$ make converge PATTERN=centos-7

When you’re done testing, you can clean everything up with:

$ make destroy-all

Basic Beats Configuration

All configuration options for Beats are supported. You use a parameter called beat_conf to set these options, which gets written into the ${beat}.yml file. Using this method means you won’t need to change your Ansible playbook as new settings are added or changed.

Here’s an example of configuring a Packetbeat instance:

- name: Example playbook for installing packetbeat
  hosts: localhost
  roles:
    - { role: beats, beat: "packetbeat",
        beat_conf: {
          "interfaces": {"device":"any"},
          "protocols": {
            "dns": {
              "ports": [53],
              "include_authorities": true
            },
            "http": {
              "ports": [80, 8080, 8000, 5000, 8002]
            },
            ...
          }
        },
        output_conf : {
          "elasticsearch": {
            "hosts": ["localhost:9200"]
          }
        }
    }
  vars:
    use_repository: "true"

Additional Configuration

Here are some important parameters you can set:

• beat (REQUIRED): Specifies which Beat to install, such as "filebeat", "metricbeat", or "packetbeat." Other Beats from The Beats Family might work too but are not tested.
• beat_conf (REQUIRED): Configuration for the selected Beat; it must be a map.
• beats_version (Defaults to 7.17.0): The version of Beats you want to install.
• version_lock (Defaults to false): If set to true, it prevents automatic updates to the installed version.
• use_repository (Defaults to true): Use the Elastic repository for package management.
• start_service (Defaults to true): If true, it will start the service.
• restart_on_change (Defaults to true): If there are any changes in configuration or versions, the service will restart if this is true.

Focus on ILM

By default, the Beat will create a standard policy based on the deployment. You can change this by defining your ILM setup in the beat_conf.

Example:

- role: ansible-beats
  beat: metricbeat
  beat_conf:
    setup:
      ilm:
        policy_file: /etc/filebeat/policies/my-default-metricbeat.json
        overwrite: true
  default_ilm_policy: conf/my-default-metricbeat.json

This will copy your custom file to the appropriate directory and set it as the default policy for the Beat.

License

Apache 2.0

Limitations

You cannot install multiple instances of the same Beat on one server.

Questions on Usage

If you have questions about using this role, feel free to ask. However, to keep the GitHub issues organized, please post questions on https://discuss.elastic.co/c/beats instead. This forum is monitored by the maintainers.

Community contributions are always welcome! Please include tests with your contributions where appropriate.