From 80be08d7dce98da3db690ee127ec6b8793e1a63d Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 11:49:51 +0200 Subject: [PATCH 01/10] Word the repository requirement the same way in every role (cherry picked from commit 79e9378bd3406ec9b49c2f30286633afca364446) --- roles/beats/README.md | 2 +- roles/elasticsearch/README.md | 2 +- roles/kibana/README.md | 2 +- roles/logstash/README.md | 3 +-- 4 files changed, 4 insertions(+), 5 deletions(-) diff --git a/roles/beats/README.md b/roles/beats/README.md index 41d70ece..d26da0dd 100644 --- a/roles/beats/README.md +++ b/roles/beats/README.md @@ -5,7 +5,7 @@ Installs and configures the Elastic [Beats](https://www.elastic.co/beats) — Fi ## Requirements * The `community.crypto` collection (used to check certificate expiration). -* The Beats you want to install must be available in your software repositories — use the [`repos`](../repos) role or provide them yourself. +* The Elastic repositories configured: use the [`repos`](../repos/README.md) role or provide them yourself. ## Example diff --git a/roles/elasticsearch/README.md b/roles/elasticsearch/README.md index 9594c953..837b9542 100644 --- a/roles/elasticsearch/README.md +++ b/roles/elasticsearch/README.md @@ -6,7 +6,7 @@ The OSS variant is only available up to Elastic Stack 7; from release 8 on only ## Requirements -* The Elastic repositories configured — use the [`repos`](../repos) role. +* The Elastic repositories configured: use the [`repos`](../repos/README.md) role or provide them yourself. * For the default security setup the role generates certificates with the bundled `elasticsearch-certutil` and `openssl`. The required Python libraries (`cryptography`, `elasticsearch`) are installed for you by the shared `elasticstack` role. ## Example diff --git a/roles/kibana/README.md b/roles/kibana/README.md index 68cf3a21..40f9d2b1 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -4,7 +4,7 @@ Installs and configures [Kibana](https://www.elastic.co/kibana) on Linux systems ## Requirements -* The Elastic repositories configured — use the [`repos`](../repos) role. +* The Elastic repositories configured: use the [`repos`](../repos/README.md) role or provide them yourself. * A reachable Elasticsearch instance for Kibana to connect to. * For browser-facing TLS (`kibana_tls: true`): a certificate and key from a CA your users trust (corporate PKI or a public CA), provided via `kibana_tls_cert` and `kibana_tls_key`. The role does **not** generate a browser certificate. diff --git a/roles/logstash/README.md b/roles/logstash/README.md index eaa1ee4d..d16d8e3d 100644 --- a/roles/logstash/README.md +++ b/roles/logstash/README.md @@ -11,8 +11,7 @@ It works with the standard Elastic Stack packages and with Elastic's OSS variant * `curl` on the target host. * `git` on the target host if you use git-based pipelines. * Redis if you use the default pipeline or other pipelines that talk to Redis (e.g. via the [`geerlingguy.redis`](https://galaxy.ansible.com/geerlingguy/redis) role). - -You also need the Elastic repositories configured — use the [`repos`](../repos) role. +* The Elastic repositories configured: use the [`repos`](../repos/README.md) role or provide them yourself. ## Example From 8565117655dfdded89ef126114f09f713d33fdd7 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 11:51:32 +0200 Subject: [PATCH 02/10] Drop requirements that state the obvious or repeat the intro (cherry picked from commit c35dba0ca2662449419dda3e9f05063b786d2563) --- roles/elasticstack/README.md | 2 +- roles/kibana/README.md | 1 - roles/repos/README.md | 1 - 3 files changed, 1 insertion(+), 3 deletions(-) diff --git a/roles/elasticstack/README.md b/roles/elasticstack/README.md index 2d20d381..0f2b2317 100644 --- a/roles/elasticstack/README.md +++ b/roles/elasticstack/README.md @@ -6,7 +6,7 @@ Set these variables once (in `group_vars`, the play, or via `-e`) and every role ## Requirements -You do not run this role directly — the component roles import it automatically. It installs the shared Python libraries (`cryptography` and the `elasticsearch` client) and packages (`openssl`, `unzip`) that the collection needs. +It installs the shared Python libraries (`cryptography` and the `elasticsearch` client) and the packages (`openssl`, `unzip`) that the collection needs. ## Example diff --git a/roles/kibana/README.md b/roles/kibana/README.md index 40f9d2b1..c0375191 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -5,7 +5,6 @@ Installs and configures [Kibana](https://www.elastic.co/kibana) on Linux systems ## Requirements * The Elastic repositories configured: use the [`repos`](../repos/README.md) role or provide them yourself. -* A reachable Elasticsearch instance for Kibana to connect to. * For browser-facing TLS (`kibana_tls: true`): a certificate and key from a CA your users trust (corporate PKI or a public CA), provided via `kibana_tls_cert` and `kibana_tls_key`. The role does **not** generate a browser certificate. ## Example diff --git a/roles/repos/README.md b/roles/repos/README.md index c0ca4562..2953130d 100644 --- a/roles/repos/README.md +++ b/roles/repos/README.md @@ -7,7 +7,6 @@ Its main use is together with the other roles of this collection, which expect t ## Requirements * The `community.general` collection — only needed on SUSE hosts, where the role uses the `zypper` modules. -* Network access from the target host to the Elastic repository URL. The role installs the required signing tools (`gpg`/`gnupg`) itself. From 765f6f1f003bb1563c82f0459735be461c642473 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 11:54:57 +0200 Subject: [PATCH 03/10] Replace the em dashes in the documentation and comments (cherry picked from commit d6b3b685d501ae892860cfd45122f8bc2e938ec5) --- roles/beats/README.md | 10 +++++----- roles/beats/docs/filebeat-inputs.md | 8 ++++---- roles/beats/meta/argument_specs.yml | 2 +- roles/elasticsearch/README.md | 6 +++--- roles/elasticsearch/tasks/elasticsearch-security.yml | 2 +- roles/elasticstack/README.md | 2 +- roles/kibana/README.md | 6 +++--- roles/kibana/tasks/main.yml | 2 +- roles/logstash/README.md | 10 +++++----- roles/repos/README.md | 4 ++-- 10 files changed, 26 insertions(+), 26 deletions(-) diff --git a/roles/beats/README.md b/roles/beats/README.md index d26da0dd..ce918d78 100644 --- a/roles/beats/README.md +++ b/roles/beats/README.md @@ -1,6 +1,6 @@ # Ansible Role: Beats -Installs and configures the Elastic [Beats](https://www.elastic.co/beats) — Filebeat, Auditbeat and Metricbeat — on Linux systems. The role can run standalone or together with the other Elastic Stack roles. Beats can ship to Logstash or directly to Elasticsearch. +Installs and configures the Elastic [Beats](https://www.elastic.co/beats) on Linux systems: Filebeat, Auditbeat and Metricbeat. The role can run standalone or together with the other Elastic Stack roles. Beats can ship to Logstash or directly to Elasticsearch. ## Requirements @@ -27,9 +27,9 @@ Filebeat can read from several sources (log files, syslog, journald, Docker, mod Run only parts of the role with `--tags`: -* `configuration` (alias `beats_configuration`) — (re)write the Filebeat and Auditbeat configuration without installing. Use `beats_filebeat_configuration` or `beats_auditbeat_configuration` to limit it to one of them. -* `certificates` — only generate and distribute the TLS certificates. -* `renew_beats_cert` / `renew_ca` — force renewal of the Beats certificate. +* `configuration` (alias `beats_configuration`): (re)write the Filebeat and Auditbeat configuration without installing. Use `beats_filebeat_configuration` or `beats_auditbeat_configuration` to limit it to one of them. +* `certificates`: only generate and distribute the TLS certificates. +* `renew_beats_cert` / `renew_ca`: force renewal of the Beats certificate. ## Role variables @@ -40,7 +40,7 @@ Run only parts of the role with `--tags`: | `beats_auditbeat`
**Type**: `bool`
**Default**: `false` | Install and manage Auditbeat. | | `beats_metricbeat`
**Type**: `bool`
**Default**: `false` | Install and manage Metricbeat. | | `beats_target_hosts`
**Type**: `list` of `str`
**Default**: `['localhost']` | Hosts the Beats ship to. Only used when the role runs standalone; with the other Elastic Stack roles the targets are determined automatically. | -| `beats_fields`
**Type**: `list` of `str` | Global fields added to the log and syslog (tcp/udp) inputs (not to the mysql, journald or docker inputs), given as a list of "key: value" strings — the global counterpart to the per-input fields. Unset by default. See the Filebeat inputs documentation. | +| `beats_fields`
**Type**: `list` of `str` | Global fields added to the log and syslog (tcp/udp) inputs (not to the mysql, journald or docker inputs), given as a list of "key: value" strings. This is the global counterpart to the per-input fields. Unset by default. See the Filebeat inputs documentation. | | `beats_logging`
**Type**: `str`
**Default**: `"file"` | Where the Beats log. Set to "file" to log into beats_logpath; any other value leaves the Beats built-in logging. | | `beats_loglevel`
**Type**: `str`
**Default**: `"info"` | Log level for all Beats. | | `beats_logpath`
**Type**: `str`
**Default**: `"/var/log/beats"` | Directory for the log files when beats_logging is "file". | diff --git a/roles/beats/docs/filebeat-inputs.md b/roles/beats/docs/filebeat-inputs.md index fc34a002..a7d9e442 100644 --- a/roles/beats/docs/filebeat-inputs.md +++ b/roles/beats/docs/filebeat-inputs.md @@ -6,7 +6,7 @@ Filebeat can read from several sources. Each source is turned into a Filebeat in Set with `beats_filebeat_log_input` (default `true`) and `beats_filebeat_log_inputs`. -`beats_filebeat_log_inputs` is a **dictionary keyed by a free name**. That key becomes the id of the generated [`filestream`](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-filestream) input (`-filestream`) — there is no separate `name` field. Each entry needs `paths`; `fields` and `multiline` are optional. +`beats_filebeat_log_inputs` is a **dictionary keyed by a free name**. That key becomes the id of the generated [`filestream`](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-filestream) input (`-filestream`). There is no separate `name` field. Each entry needs `paths`; `fields` and `multiline` are optional. The default reads the system log: @@ -40,7 +40,7 @@ beats_filebeat_log_inputs: There are two ways to add fields, and they use **different shapes**: -* **Per input** — the optional `fields` inside a log input is a **dictionary** (`key: value`), added only to that input: +* **Per input**: the optional `fields` inside a log input is a **dictionary** (`key: value`), added only to that input: ```yaml beats_filebeat_log_inputs: @@ -51,7 +51,7 @@ There are two ways to add fields, and they use **different shapes**: environment: production ``` -* **Globally** — `beats_fields` is a **list of `"key: value"` strings**. In the current templates it is added to the log, TCP and UDP inputs; the journald, Docker and MySQL slow-log inputs do not receive it: +* **Globally**: `beats_fields` is a **list of `"key: value"` strings**. In the current templates it is added to the log, TCP and UDP inputs; the journald, Docker and MySQL slow-log inputs do not receive it: ```yaml beats_fields: @@ -72,7 +72,7 @@ beats_filebeat_syslog_tcp_port: 514 Enable with `beats_filebeat_journald` (default `false`, available since Filebeat 7.16) and configure inputs with `beats_filebeat_journald_inputs`. -This is a **dictionary keyed by a free name**. Unlike the log inputs, here the key is only a label — the input's id comes from the `id` field, which each entry needs. `include_matches` is optional and is itself a dictionary whose values are the match expressions. +This is a **dictionary keyed by a free name**. Unlike the log inputs, here the key is only a label. The input's id comes from the `id` field, which each entry needs. `include_matches` is optional and is itself a dictionary whose values are the match expressions. ```yaml beats_filebeat_journald_inputs: diff --git a/roles/beats/meta/argument_specs.yml b/roles/beats/meta/argument_specs.yml index c6ae8aa9..efa7d4e0 100644 --- a/roles/beats/meta/argument_specs.yml +++ b/roles/beats/meta/argument_specs.yml @@ -55,7 +55,7 @@ argument_specs: description: >- Global fields added to the log and syslog (tcp/udp) inputs (not to the mysql, journald or docker inputs), given as a list of "key: value" - strings — the global counterpart to the per-input fields. Unset by + strings. This is the global counterpart to the per-input fields. Unset by default. See the Filebeat inputs documentation. # ----- Logging ----- diff --git a/roles/elasticsearch/README.md b/roles/elasticsearch/README.md index 837b9542..69d666b6 100644 --- a/roles/elasticsearch/README.md +++ b/roles/elasticsearch/README.md @@ -25,9 +25,9 @@ The OSS variant is only available up to Elastic Stack 7; from release 8 on only Run only parts of the role with `--tags`: -* `certificates` — only generate and distribute the TLS certificates. -* `renew_es_cert` — force renewal of the Elasticsearch node certificate. -* `renew_ca` — force renewal of the stack CA and all component certificates. +* `certificates`: only generate and distribute the TLS certificates. +* `renew_es_cert`: force renewal of the Elasticsearch node certificate. +* `renew_ca`: force renewal of the stack CA and all component certificates. ## Role variables diff --git a/roles/elasticsearch/tasks/elasticsearch-security.yml b/roles/elasticsearch/tasks/elasticsearch-security.yml index 84f90609..9b71a36a 100644 --- a/roles/elasticsearch/tasks/elasticsearch-security.yml +++ b/roles/elasticsearch/tasks/elasticsearch-security.yml @@ -231,7 +231,7 @@ # Pass passphrases via argv (a list), not a folded shell string. A string command is # tokenized by shlex.split() (shell-like word splitting and quote parsing), which mangles # passphrases containing spaces or quotes. With argv every element is handed to the binary - # literally — no shell, no shlex — so arbitrary special characters work. + # literally, with no shell and no shlex, so arbitrary special characters work. - name: Configure ca on elasticstack_ca_host ansible.builtin.command: argv: diff --git a/roles/elasticstack/README.md b/roles/elasticstack/README.md index 0f2b2317..1b27c92a 100644 --- a/roles/elasticstack/README.md +++ b/roles/elasticstack/README.md @@ -1,6 +1,6 @@ # Ansible Role: elasticstack -The shared base role of the collection. Every component role (elasticsearch,logstash, kibana, beats, repos) imports it automatically on first use, so you normally do not call it directly. It installs the common dependencies and, above all, defines the collection-wide `elasticstack_*` variables — the settings shared across all roles: release and variant, the inventory host groups, ports, the package repositories, and the stack CA. +The shared base role of the collection. Every component role (elasticsearch, logstash, kibana, beats, repos) imports it automatically on first use, so you normally do not call it directly. It installs the common dependencies and, above all, defines the collection-wide `elasticstack_*` variables, the settings shared across all roles: release and variant, the inventory host groups, ports, the package repositories, and the stack CA. Set these variables once (in `group_vars`, the play, or via `-e`) and every role picks them up. This page is the central reference for them. diff --git a/roles/kibana/README.md b/roles/kibana/README.md index c0375191..fe02e630 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -1,6 +1,6 @@ # Ansible Role: Kibana -Installs and configures [Kibana](https://www.elastic.co/kibana) on Linux systems. The role manages `kibana.yml` and can enable TLS for the Kibana web interface, using a certificate you provide. In a full stack setup together with the elasticsearch role, it also configures the connection to Elasticsearch — the TLS trust and the `kibana_system` credentials — using the Elasticsearch CA. +Installs and configures [Kibana](https://www.elastic.co/kibana) on Linux systems. The role manages `kibana.yml` and can enable TLS for the Kibana web interface, using a certificate you provide. In a full stack setup together with the elasticsearch role, it also configures the connection to Elasticsearch, both the TLS trust and the `kibana_system` credentials, using the Elasticsearch CA. ## Requirements @@ -43,8 +43,8 @@ This writes `/var/log/kibana/kibana.log` in a human readable layout and keeps te Run only parts of the role with `--tags`: -* `certificates` — only generate and distribute the TLS certificates. -* `renew_kibana_cert` / `renew_ca` — force renewal of the Kibana certificate. +* `certificates`: only generate and distribute the TLS certificates. +* `renew_kibana_cert` / `renew_ca`: force renewal of the Kibana certificate. ## Role variables diff --git a/roles/kibana/tasks/main.yml b/roles/kibana/tasks/main.yml index 8a58acda..f178f2ee 100644 --- a/roles/kibana/tasks/main.yml +++ b/roles/kibana/tasks/main.yml @@ -139,7 +139,7 @@ # ready yet") until it is fully up, so downstream consumers (e.g. Beats # dashboard setup) must not race it. Poll unauthenticated: a ready Kibana # answers 200 (anonymous status allowed) or 401 (auth required but server up) - # depending on status.allowAnonymous / the version — treat both as ready. + # depending on status.allowAnonymous and the version. Treat both as ready. - name: Wait for Kibana API to be ready ansible.builtin.uri: url: "{{ 'https' if kibana_tls | bool else 'http' }}://localhost:{{ elasticstack_kibana_port }}/api/status" diff --git a/roles/logstash/README.md b/roles/logstash/README.md index d16d8e3d..ace92725 100644 --- a/roles/logstash/README.md +++ b/roles/logstash/README.md @@ -1,6 +1,6 @@ # Ansible Role: Logstash -Installs and configures [Logstash](https://www.elastic.co/products/logstash) on Linux systems. The role can manage `logstash.yml`, the log4j2 logging, the JVM heap, TLS, and the Elasticsearch writer role/user. For pipelines it can create two default pipelines — a Beats input and an Elasticsearch forwarder, both using Redis — and manage your own pipelines, whose configuration can be checked out from external git repositories. +Installs and configures [Logstash](https://www.elastic.co/products/logstash) on Linux systems. The role can manage `logstash.yml`, the log4j2 logging, the JVM heap, TLS, and the Elasticsearch writer role/user. For pipelines it can create two default pipelines, a Beats input and an Elasticsearch forwarder both using Redis, and manage your own pipelines, whose configuration can be checked out from external git repositories. It works with the standard Elastic Stack packages and with Elastic's OSS variant. @@ -33,10 +33,10 @@ For how to configure pipelines (built-in Redis/Beats and external git repositori Run only parts of the role with `--tags`: -* `configuration` (alias `logstash_configuration`) — only (re)write the configuration, skip installation. -* `certificates` — only generate and distribute the TLS certificates. -* `renew_logstash_cert` / `renew_ca` — force renewal of the Logstash certificate. -* `mermaid` — only regenerate the pipeline overview (`pipelines.mermaid`). +* `configuration` (alias `logstash_configuration`): only (re)write the configuration, skip installation. +* `certificates`: only generate and distribute the TLS certificates. +* `renew_logstash_cert` / `renew_ca`: force renewal of the Logstash certificate. +* `mermaid`: only regenerate the pipeline overview (`pipelines.mermaid`). ## Role variables diff --git a/roles/repos/README.md b/roles/repos/README.md index 2953130d..675d7b83 100644 --- a/roles/repos/README.md +++ b/roles/repos/README.md @@ -6,7 +6,7 @@ Its main use is together with the other roles of this collection, which expect t ## Requirements -* The `community.general` collection — only needed on SUSE hosts, where the role uses the `zypper` modules. +* The `community.general` collection, only needed on SUSE hosts where the role uses the `zypper` modules. The role installs the required signing tools (`gpg`/`gnupg`) itself. @@ -30,4 +30,4 @@ No variables are defined for this role. ## Shared variables -This role is configured through the collection-wide `elasticstack_*` variables — mainly `elasticstack_release`, `elasticstack_variant`, `elasticstack_enable_repos`, `elasticstack_repo_url`, `elasticstack_repo_key` and `elasticstack_rpm_workaround`. They are documented centrally with the [elasticstack role](../elasticstack/README.md). +This role is configured through the collection-wide `elasticstack_*` variables, mainly `elasticstack_release`, `elasticstack_variant`, `elasticstack_enable_repos`, `elasticstack_repo_url`, `elasticstack_repo_key` and `elasticstack_rpm_workaround`. They are documented centrally with the [elasticstack role](../elasticstack/README.md). From d9dc33185b23d94895060f554011c0a093447964 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 11:55:46 +0200 Subject: [PATCH 04/10] Remove the stale variable renaming notice and a misplaced sentence (cherry picked from commit a4aa1355f61d5d50e5b93ad15d01a8d2c9c7ad4e) --- README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/README.md b/README.md index 60838568..b61799ec 100644 --- a/README.md +++ b/README.md @@ -119,10 +119,6 @@ The execution order of the roles matters, and the roles interact with hosts from ## Caveats and information for long time users -### Variable renaming - -If you have been using this collection before version `1.0.0`, note that a significant number of variables had to be renamed because of naming schema changes made by Ansible. Please review the variables you set in your playbooks and variable files. - ### Ulimit management for Elasticsearch 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//limits`. If your version does not, please [open an issue](https://github.com/NETWAYS/ansible-collection-elasticstack/issues). @@ -131,7 +127,7 @@ The role no longer configures `ulimit`. Make sure the system's open file limit i Every kind of contribution is welcome. Open [issues](https://github.com/NETWAYS/ansible-collection-elasticstack/issues) or provide [pull requests](https://github.com/NETWAYS/ansible-collection-elasticstack/pulls). -Pull requests go against `main`. If you need a stable state, pin a release tag. +Pull requests go against `main`. Please read [CONTRIBUTING.md](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. From 0c9045103095336d7ca65e85b697de404f26f4c0 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 12:04:48 +0200 Subject: [PATCH 05/10] Correct the pipeline examples and the prose around them (cherry picked from commit 9146d1dbce7e7f381234419e2f4fcd5ad5f3d61f) --- roles/logstash/docs/pipelines.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/roles/logstash/docs/pipelines.md b/roles/logstash/docs/pipelines.md index a28f04eb..30ed90f5 100644 --- a/roles/logstash/docs/pipelines.md +++ b/roles/logstash/docs/pipelines.md @@ -2,7 +2,7 @@ ## Keeping an overview -It can be quite difficult to stay on top of your pipeline configuration because they tend to become very complex. +It can be quite difficult to stay on top of your pipeline configuration, because pipelines tend to become very complex. This collection will leave some comments about how pipelines are interconnected within the `/etc/logstash/pipelines.yml` configuration file. @@ -28,7 +28,7 @@ You can also determine where Logstash stores the data of each pipeline while pro ### Basic configuration -To have a single Redis input and output to your files, use this. +To give a pipeline one Redis input and one Redis output, use this. ```yaml logstash_pipelines: @@ -45,7 +45,7 @@ logstash_pipelines: key: syslog-output ``` -This will result in your pipeline checking out the configuration on GitHub and adding these two extras. In extra files, just shown in one place to safe space. +This will result in your pipeline checking out the configuration on GitHub and adding these two extras. The role writes them into separate files, `input.conf` and `output.conf`, they are only shown together here to save space. ``` input { @@ -72,7 +72,7 @@ Just give more inputs with `name` and `key`. Every key will be read. If you want a bit more control over which outputs are used, the role offers more sophisticated configuration. -If you have several outputs that all have conditions, like just send some messages to a development system or only alerts to a monitoring system. +This helps when several outputs each have their own condition, for example to send some messages to a development system and only alerts to a monitoring system. ```yaml logstash_pipelines: @@ -97,7 +97,7 @@ This will give you the following configuration: ``` input { -# default output +# default input redis { host => "localhost" data_type => "list" @@ -136,7 +136,7 @@ if [program] == "special2"{ } ``` -Note that the `default` output get's **every** event, the other two outputs only get those where the condition is met. +The `default` output gets **every** event, the other two outputs only get those where the condition is met. You can combine several outputs with `else`. That's helpful when you want to split events. Like syslog messages depending on which program logged an event. Just change `exclusive` to `true`. @@ -164,7 +164,7 @@ This will give you the following Logstash configuration. ``` input { -# default output +# default input redis { host => "localhost" data_type => "list" @@ -193,7 +193,7 @@ else if [program] == "special2" { } # default output -else { +else { redis { host => "localhost" data_type => "list" From 87de88ea4ec100cc75222c63c90c1349d1a822f2 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 13:35:05 +0200 Subject: [PATCH 06/10] Stop naming the tested ansible-core versions in the README (cherry picked from commit ea4bfc301efd650b52cc048efdd8bda7f3df1d5c) --- NOTICE.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/NOTICE.md b/NOTICE.md index 83d51761..d5be9b11 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -4,4 +4,4 @@ Here's a list of sponsors who contributed by having the collection improved via outsourcing to NETWAYS. -* CID GmbH : Thank you so much for sponsoring. Especially the feature to have different types of Elasticsearch nodes in the cluster and the integration of rolling upgrades. +* CID GmbH: Thank you so much for sponsoring. Especially the feature to have different types of Elasticsearch nodes in the cluster and the integration of rolling upgrades. diff --git a/README.md b/README.md index b61799ec..9f245f39 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The minimum required version is declared in [meta/runtime.yml](meta/runtime.yml) | | | |---|---| -| ansible-core | `>= 2.18`, tested with 2.19 and 2.20 | +| ansible-core | `>= 2.18` | | Python on the control node | `>= 3.11` | | Python on the target hosts | `>= 3.9` | | Elastic Stack | release 8 | From 80598febeb742ec256aa1ddcffcb2b816586d5f2 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Tue, 15 Sep 2026 14:02:44 +0200 Subject: [PATCH 07/10] Say what choosing the Beats output actually changes (cherry picked from commit bc25fa7a5037f9401299bcbbfd5654d7a24ab6fd) --- roles/beats/README.md | 6 +++--- roles/beats/meta/argument_specs.yml | 15 ++++++++++++--- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/roles/beats/README.md b/roles/beats/README.md index ce918d78..18d43373 100644 --- a/roles/beats/README.md +++ b/roles/beats/README.md @@ -45,7 +45,7 @@ Run only parts of the role with `--tags`: | `beats_loglevel`
**Type**: `str`
**Default**: `"info"` | Log level for all Beats. | | `beats_logpath`
**Type**: `str`
**Default**: `"/var/log/beats"` | Directory for the log files when beats_logging is "file". | | `beats_filebeat_enable`
**Type**: `bool`
**Default**: `true` | Start and enable the Filebeat service. | -| `beats_filebeat_output`
**Type**: `str`
**Default**: `"logstash"`
**Choices**: `logstash`, `elasticsearch` | Where Filebeat sends its events. | +| `beats_filebeat_output`
**Type**: `str`
**Default**: `"logstash"`
**Choices**: `logstash`, `elasticsearch` | Where Filebeat sends its events. With "logstash" they pass through the Logstash pipelines and can be filtered and enriched there, which is what log lines usually need. With "elasticsearch" they go straight into the cluster. | | `beats_filebeat_elastic_monitoring`
**Type**: `bool`
**Default**: `false` | Report Filebeat monitoring data through the Elastic Stack monitoring features. | | `beats_filebeat_loadbalance`
**Type**: `bool`
**Default**: `true` | Enable load balancing for the Filebeat Logstash output. | | `beats_filebeat_log_input`
**Type**: `bool`
**Default**: `true` | Read log files with the inputs from beats_filebeat_log_inputs. | @@ -61,11 +61,11 @@ Run only parts of the role with `--tags`: | `beats_filebeat_mysql_slowlog_input`
**Type**: `bool`
**Default**: `false` | Collect the MySQL/MariaDB slow query log, including multiline handling. | | `beats_filebeat_modules`
**Type**: `list` of `str` | List of Filebeat modules to enable (experimental). Unset by default. | | `beats_auditbeat_enable`
**Type**: `bool`
**Default**: `true` | Start and enable the Auditbeat service. | -| `beats_auditbeat_output`
**Type**: `str`
**Default**: `"elasticsearch"`
**Choices**: `logstash`, `elasticsearch` | Where Auditbeat sends its events. | +| `beats_auditbeat_output`
**Type**: `str`
**Default**: `"elasticsearch"`
**Choices**: `logstash`, `elasticsearch` | Where Auditbeat sends its events. Defaults to "elasticsearch" because audit events already arrive structured and gain nothing from passing through Logstash. Set it to "logstash" to route them through the pipelines anyway. | | `beats_auditbeat_setup`
**Type**: `bool`
**Default**: `true` | Run the Auditbeat setup (index management, ingest pipelines and Kibana dashboards). Only effective with the elasticsearch output; loading the dashboards additionally requires Kibana to be reachable. | | `beats_auditbeat_loadbalance`
**Type**: `bool`
**Default**: `true` | Enable load balancing for the Auditbeat Logstash output. | | `beats_metricbeat_enable`
**Type**: `bool`
**Default**: `true` | Start and enable the Metricbeat service. | -| `beats_metricbeat_output`
**Type**: `str`
**Default**: `"elasticsearch"`
**Choices**: `logstash`, `elasticsearch` | Where Metricbeat sends its events. | +| `beats_metricbeat_output`
**Type**: `str`
**Default**: `"elasticsearch"`
**Choices**: `logstash`, `elasticsearch` | Where Metricbeat sends its events. Defaults to "elasticsearch" because metrics already arrive structured and gain nothing from passing through Logstash. Set it to "logstash" to route them through the pipelines anyway. | | `beats_metricbeat_modules`
**Type**: `list` of `str`
**Default**: `['system']` | Metricbeat modules to enable. | | `beats_metricbeat_loadbalance`
**Type**: `bool`
**Default**: `true` | Enable load balancing for the Metricbeat Logstash output. | | `beats_security`
**Type**: `bool`
**Default**: `false` | Activate TLS for the connections to the targets. Works with the other roles and elasticstack_full_stack to create certificates automatically, or with the beats_tls_* variables for custom certificates. | diff --git a/roles/beats/meta/argument_specs.yml b/roles/beats/meta/argument_specs.yml index efa7d4e0..ab9988e6 100644 --- a/roles/beats/meta/argument_specs.yml +++ b/roles/beats/meta/argument_specs.yml @@ -88,7 +88,10 @@ argument_specs: - logstash - elasticsearch default: logstash - description: Where Filebeat sends its events. + description: >- + Where Filebeat sends its events. With "logstash" they pass through the Logstash + pipelines and can be filtered and enriched there, which is what log lines usually + need. With "elasticsearch" they go straight into the cluster. beats_filebeat_elastic_monitoring: type: bool @@ -183,7 +186,10 @@ argument_specs: - logstash - elasticsearch default: elasticsearch - description: Where Auditbeat sends its events. + description: >- + Where Auditbeat sends its events. Defaults to "elasticsearch" because audit events + already arrive structured and gain nothing from passing through Logstash. Set it to + "logstash" to route them through the pipelines anyway. beats_auditbeat_setup: type: bool @@ -210,7 +216,10 @@ argument_specs: - logstash - elasticsearch default: elasticsearch - description: Where Metricbeat sends its events. + description: >- + Where Metricbeat sends its events. Defaults to "elasticsearch" because metrics + already arrive structured and gain nothing from passing through Logstash. Set it to + "logstash" to route them through the pipelines anyway. beats_metricbeat_modules: type: list From 04d2c6b88bab63b130d72f6c8fb73f66208e9153 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 16 Sep 2026 15:01:28 +0200 Subject: [PATCH 08/10] Fix a leftover filler word and add the changelog fragment --- changelogs/fragments/docs_wording_cleanup.yml | 8 ++++++++ roles/logstash/docs/pipelines.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/docs_wording_cleanup.yml diff --git a/changelogs/fragments/docs_wording_cleanup.yml b/changelogs/fragments/docs_wording_cleanup.yml new file mode 100644 index 00000000..d803aa94 --- /dev/null +++ b/changelogs/fragments/docs_wording_cleanup.yml @@ -0,0 +1,8 @@ +trivial: + - The repository requirement is worded the same way in all four roles that need it, and the + requirements that stated the obvious are gone. + - The pipelines documentation no longer labels the generated Redis input block as an output, + and the prose around the examples says what the role actually does. + - "The three ``beats__output`` descriptions now say what choosing each value changes + instead of repeating the variable name, the README no longer names the tested ansible-core + versions, and the stale variable renaming notice is removed." diff --git a/roles/logstash/docs/pipelines.md b/roles/logstash/docs/pipelines.md index 30ed90f5..60e31aff 100644 --- a/roles/logstash/docs/pipelines.md +++ b/roles/logstash/docs/pipelines.md @@ -221,7 +221,7 @@ If you need unsafe Logstash shutdowns, e.g. for testing, you can set `logstash_p There are still some minor issues you need to keep in mind: -* The default output in an `exclusive: true` setup must be the last in the YAML configuration. There's no sorting, the role simply expects the default to be the last one. +* The default output in an `exclusive: true` setup must be the last in the YAML configuration. There's no sorting, the role expects the default to be the last one. * The configuration *should* work but will make no sense if you have `exclusive: true` but two or more outputs without `condition`. ## Custom pipelines From d1109b30ab6d1d787d0b908414ee617fe448bce4 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 16 Sep 2026 15:15:27 +0200 Subject: [PATCH 09/10] Name the two check jobs after what they verify --- .github/workflows/test_changelog.yml | 2 +- .github/workflows/test_docs.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test_changelog.yml b/.github/workflows/test_changelog.yml index 8966ab43..ab445dd9 100644 --- a/.github/workflows/test_changelog.yml +++ b/.github/workflows/test_changelog.yml @@ -21,7 +21,7 @@ permissions: contents: read jobs: - fragment: + changelog_fragment: # Dependabot only bumps action and dependency versions, which needs no fragment. if: >- github.event.pull_request.draft == false diff --git a/.github/workflows/test_docs.yml b/.github/workflows/test_docs.yml index 59824543..cd95b703 100644 --- a/.github/workflows/test_docs.yml +++ b/.github/workflows/test_docs.yml @@ -17,7 +17,7 @@ concurrency: cancel-in-progress: true jobs: - docs: + argument_specs_and_readme: # For non-PR events (workflow_dispatch, etc.), github.event.pull_request.draft is null. # GitHub Actions coerces null == false to true, so the job runs for all non-draft events. if: github.event.pull_request.draft == false From c79276ee312be5c9b25a9709cc835d5c3b01858d Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 16 Sep 2026 15:15:57 +0200 Subject: [PATCH 10/10] Note the job rename in the changelog fragment --- changelogs/fragments/docs_wording_cleanup.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/fragments/docs_wording_cleanup.yml b/changelogs/fragments/docs_wording_cleanup.yml index d803aa94..a02b61ac 100644 --- a/changelogs/fragments/docs_wording_cleanup.yml +++ b/changelogs/fragments/docs_wording_cleanup.yml @@ -6,3 +6,5 @@ trivial: - "The three ``beats__output`` descriptions now say what choosing each value changes instead of repeating the variable name, the README no longer names the tested ansible-core versions, and the stale variable renaming notice is removed." + - The two check jobs are named after what they verify, ``argument_specs_and_readme`` and + ``changelog_fragment``, so the status check on a pull request says which condition failed.