Ansible Collection Elasticstack

This collection installs and manages the Elastic Stack. It provides roles for every component of the Stack, and it can install either the default Elastic distribution or the Apache-licensed OSS packages.

Every role can be used on its own or together with the others. Running a single role against an existing or external cluster works, but a few of those paths are still incomplete. See the open issues for details.

The minimum required version is declared in meta/runtime.yml and enforced by ansible-galaxy on install.

We test on the following Linux distributions, each one with Elastic Stack 8:

• Rocky Linux 9
• Ubuntu 22.04 LTS
• Debian 13

Ansible collections, both are declared as dependencies and installed for you when you install this collection with ansible-galaxy:

• community.general, for the zypper modules on SUSE hosts and the Logstash plugin module
• community.crypto, used by the beats role to check when a certificate expires

Python libraries on the control node:

• passlib, unless you disable password hashing for the Logstash user and you want to use the logstash role. Install it with pip.
• elasticsearch. Current versions are compatible either with Elasticsearch 9 or with versions lower than 9, there seems to be no version that serves both. For now we install a client older than 9, and this needs revisiting when the collection becomes compatible with Elastic Stack 9.

Ansible roles:

• geerlingguy.redis if you want to use the logstash role. There are other ways to get Redis running, but this one is easy and convenient.

  ansible-galaxy install geerlingguy.redis

Some very basic packages such as openssl are handled by the collection itself. The list above only contains what applies to special cases or what you need to decide about yourself.

Beyond software, the roles expect a few things from your inventory. See Requirements.

Roles:

• beats
• elasticsearch
• kibana
• logstash
• repos
• elasticstack, the meta role that holds the collection-wide elasticstack_* variables

Modules:

• cert_info, reads information from a PKCS12 certificate
• elasticsearch_role, creates, updates and deletes roles in Elasticsearch
• elasticsearch_user, creates, updates and deletes users in Elasticsearch

Each module documents its own parameters, return values and examples. Read them with ansible-doc, for example:

ansible-doc netways.elasticstack.elasticsearch_role

• Getting started, example playbook, inventory groups, first run
• Requirements, what the roles expect from your inventory
• Versions and upgrades, pinning versions and upgrading the stack

Every role documents all of its variables in its own README, linked above. Those tables are generated from each role's meta/argument_specs.yml. Module documentation comes from the modules themselves and is read with ansible-doc.

Install the collection with ansible-galaxy:

ansible-galaxy collection install netways.elasticstack

To pin a version, use a requirements.yml:

collections:
  - name: netways.elasticstack
    version: 0.1.0

ansible-galaxy collection install -r requirements.yml

The same file works for Tower and AWX. You can also install straight from git, which gives you the current state of main instead of a release:

ansible-galaxy collection install git+https://github.com/NETWAYS/ansible-collection-elasticstack.git

Then name the collection in the play and refer to the roles by their short name:

- hosts: elasticsearch
  become: true
  collections:
    - netways.elasticstack
  roles:
    - elasticsearch

Fully qualified role names such as netways.elasticstack.elasticsearch work as well and need no collections entry.

The execution order of the roles matters, and the roles interact with hosts from other inventory groups. Read Getting started before your first run.

The role no longer configures ulimit. Make sure the system's open file limit is set correctly, packages usually handle this. Verify with ulimit -n or by checking /proc/<pid>/limits. If your version does not, please open an issue.

Every kind of contribution is welcome. Open issues or provide pull requests.

Pull requests go against main.

Please read CONTRIBUTING.md first. It describes what a pull request needs, including the changelog fragment that every pull request has to bring along, how role variables are documented and how to run the tests.

See the releases page. The same notes are collected in CHANGELOG.md, which is generated from the changelog fragments when a version is released.

GPL-3.0-or-later, see LICENSE.