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 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 60838568..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 | @@ -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. diff --git a/changelogs/fragments/docs_wording_cleanup.yml b/changelogs/fragments/docs_wording_cleanup.yml new file mode 100644 index 00000000..a02b61ac --- /dev/null +++ b/changelogs/fragments/docs_wording_cleanup.yml @@ -0,0 +1,10 @@ +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." + - 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. diff --git a/roles/beats/README.md b/roles/beats/README.md index 41d70ece..18d43373 100644 --- a/roles/beats/README.md +++ b/roles/beats/README.md @@ -1,11 +1,11 @@ # 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 * 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 @@ -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,12 +40,12 @@ 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". | | `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/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..ab9988e6 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 ----- @@ -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 diff --git a/roles/elasticsearch/README.md b/roles/elasticsearch/README.md index 9594c953..69d666b6 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 @@ -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 2d20d381..1b27c92a 100644 --- a/roles/elasticstack/README.md +++ b/roles/elasticstack/README.md @@ -1,12 +1,12 @@ # 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. ## 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 68cf3a21..fe02e630 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -1,11 +1,10 @@ # 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 -* The Elastic repositories configured — use the [`repos`](../repos) role. -* A reachable Elasticsearch instance for Kibana to connect to. +* The Elastic repositories configured: use the [`repos`](../repos/README.md) role or provide them yourself. * 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 @@ -44,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 eaa1ee4d..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. @@ -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 @@ -34,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/logstash/docs/pipelines.md b/roles/logstash/docs/pipelines.md index a28f04eb..60e31aff 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" @@ -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 diff --git a/roles/repos/README.md b/roles/repos/README.md index c0ca4562..675d7b83 100644 --- a/roles/repos/README.md +++ b/roles/repos/README.md @@ -6,8 +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. -* Network access from the target host to the Elastic repository URL. +* 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. @@ -31,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).