NETWAYS · mkayontour · Jan 24, 2023 · Jan 20, 2023 · Jan 20, 2023 · Jan 20, 2023
diff --git a/AUTHORS b/AUTHORS
@@ -7,3 +7,4 @@ Nathaniel Donahue <[email protected]>
 Patrick Dolinic <[email protected]>
 Shittu Ayomide <[email protected]>
 Thomas Widhalm <[email protected]>
+Thilo Wening <[email protected]>
diff --git a/README.md b/README.md
@@ -1,11 +1,46 @@
 # Ansible Collection - netways.elasticstack
 
-Documentation for the collection.
+This collection installs and manages the Elastic Stack. It provides roles every component which is part of the Stack. Furthermore it is possible to differentiate between Enterprise or OSS releases. Every role is documented with all variables, please refer to the documentation found in **[Getting-Started](./docs/getting-started.md)**
 
-## Roles
+
+
+## Roles Documentation
 
 * [Beats](docs/role-beats.md)
 * [Elasticsearch](docs/role-elasticsearch.md)
 * [Kibana](docs/role-kibana.md)
 * [Logstash](docs/role-logstash.md)
 * [Repos](docs/role-repos.md)
+
+## Installation
+
+You can easily install the collection with the ansible-galaxy command.
+
+```
+ansible-galaxy collection install netways.elasticstack
+```
+
+Or if you are using Tower or AWX add the collection to your requirements file.
+
+```
+collections:
+  - name: netways.elasticstack
+```
+
+## Usage
+
+```
+- name: Install Elasticsearch
+  hosts: all
+  collections:
+    - NETWAYS.elasticstack
+  vars:
+    elastic_variant: oss
+    elasticsearch_jna_workaround: true
+  roles:
+    - repos
+    - beats
+    - elasticsearch
+    - logstash
+    - kibana
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,63 @@
+Collection Elastic Stack
+-------------------------
+
+Installation
+-----------
+
+You can easily install the collection with the ansible-galaxy command.
+
+```
+ansible-galaxy collection install netways.elasticstack
+```
+
+Or if you are using Tower or AWX add the collection to your requirements file.
+
+```
+collections:
+  - name: NETWAYS.elasticstack
+```
+
+Usage
+---------
+
+To use the collection in your Ansible playbook add the following key to your playbook.
+
+```
+- name: Playbook
+  hosts: some_host_pattern
+  collections:
+    - NETWAYS.elasticstack
+  tasks:
+    - name: import role logstash
+      import_role:
+        name: logstash
+```
+
+Or refer to the role with the FQCN of the role.
+
+```
+- name: Playbook
+  hosts: some_host_pattern
+  tasks:
+    - name: import role by FQCN  from a collection
+      import_role:
+        name: NETWAYS.elasticstack.logstash
+```
+
+Roles
+-------
+
+* [Beats](docs/role-beats.md)
+* [Elasticsearch](docs/role-elasticsearch.md)
+* [Kibana](docs/role-kibana.md)
+* [Logstash](docs/role-logstash.md)
+* [Repos](docs/role-repos.md)
+
+
+Variables
+-----------
+
+Every role got its own set of variables, in addition a few variables are useable on any role. Below are all general collection vars.
+
+* *elastic_release*: Major release version of Elastic stack to configure. (default: `7`)
+* *elastic_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`)
diff --git a/docs/role-beats.md b/docs/role-beats.md
@@ -1,20 +1,20 @@
 Ansible Role: Beats
 =========
 
-[![CI](https://github.com/NETWAYS/ansible-collection-elasticstack/workflows/Test%20Role%20beats/badge.svg?event=push)](https://github.com/NETWAYS/ansible-collection-elasticstack/workflows/Test%20Role%20beats/badge.svg)
+![Test Role Beats](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_beats.yml/badge.svg)
 
 This role installs and configures Beats. You can use it as a standalone role or combine it with our other roles managing the Elastic Stack.
 
 Requirements
 ------------
 
-You need to have the beats you want to install available in your software repositories. We provide a role for just that but if you have other ways of managing software, just make sure it's available. Alternatively you can install the Beats yourself.
+You need to have the beats you want to install available in your software repositories. We provide a [role](./role-repos.md) for just that but if you have other ways of managing software, just make sure it's available. Alternatively you can install the Beats yourself.
 
 Role Variables
 --------------
 
 * *beats_filebeat*: Install and manage filebeat (Default: `true`)
-* *beats_filebeat_version*: Install specific version (Default: none. Possible values: e.g. ``-7.10.1` for RedHat compatible systems or `=1:7.10.1-1` for Debian compatible systems or `latest`)
+* *beats_filebeat_version*: Install specific version (Default: none. Possible values: e.g. `-7.10.1` for RedHat compatible systems or `=1:7.10.1-1` for Debian compatible systems or `latest`)
 * *filebeat_enable*: Automatically start Filebeat (Default: `true`)
 * *filebeat_output*: Set to `logstash` or `elasticsearch`. (default: `logstash`)
 * *filebeat_syslog_udp*: Use UDP Syslog input (Default: `false`)
@@ -26,12 +26,14 @@ Role Variables
 * *filebeat_log_inputs*: Logfiles to read (Default: see below)
 
 Default of `filebeat_log_inputs`
+
 ```
   messages:
     name: messages
     paths:
       - /var/log/messages
 ```
+
 You can optionally add `fields` to every input as well. You can also add a `multiline` section with options (`type`, `pattern`, `negate` and `match` so far)
 
 Here's a longer example for an input:
@@ -51,7 +53,7 @@ filebeat_log_inputs:
 ```
 * *filebeat_journald*: Enable collection of JournalD logs (default: `false`) - available since Filebeat 7.16
 * *filebeat_journald_inputs*: List of journald inputs. Use for different filters on events. You can add a list of `include_matches` entries for filtering.
-Default of `filebeat_journald_inputs:
+Default of `filebeat_journald_inputs`:
 ```
 filebeat_journald_inputs:
   everything:
@@ -63,14 +65,14 @@ filebeat_journald_inputs:
 * *filebeat_loadbalance*: Enable loadbalancing for Filebeats Logstash output (default: `true`)
 
 * *beats_auditbeat*: Install and manage filebeat (Default: `false`)
-* *beats_auditbeat_version*: Install specific version (Default: none. Possible values: e.g. ``-7.10.1` for RedHat compatible systems or `=1:7.10.1-1` for Debian compatible systems or `latest`)
+* *beats_auditbeat_version*: Install specific version (Default: none. Possible values: e.g. `-7.10.1` for RedHat compatible systems or `=1:7.10.1-1` for Debian compatible systems or `latest`)
 * *auditbeat_output*: Output for Auditbeat Set to `logstash` or `elasticsearch`. (default: `elasticsearch`)
 * *auditbeat_enable*: Automatically start Auditbeat (Default: `true`)
 * *auditbeat_setup*: Run Auditbeat Setup (Default: `true`) (Only works with Elasticsearch output)
 * *auditbeat_loadbalance*: Enable loadbalancing for Auditbeats Logstash output (default: `true`)
 
 * *beats_metricbeat*: Enable installation and management of Metricbeat (Default: `false`)
-* *beats_metricbeat_version*: Install specific version (Default: none. Possible values: e.g. ``-7.10.1` for RedHat compatible systems or `=1:7.10.1-1` for Debian compatible systems or `latest`)
+* *beats_metricbeat_version*: Install specific version (Default: none. Possible values: e.g. `-7.10.1` for RedHat compatible systems or `=1:7.10.1-1` for Debian compatible systems or `latest`)
 * *metricbeat_enable*: Start Metricbeat automatically (Default: `true`)
 * *metricbeat_output*: Set to `logstash` or `elasticsearch`. (default: `elasticsearch`)
 * *metricbeat_modules*: List of modules to enable. (Default: `- system`)
@@ -88,7 +90,7 @@ filebeat_journald_inputs:
 
 The following variables only apply if you use this role together with our other Elastic Stack roles.
 
-* *elastic_stack_full_stack*: Use `ansible-role-elasticsearch` as well (default: `false`)
+* *elastic_stack_full_stack*: Use `elasticsearch` as well (default: `false`)
 * *elastic_variant*: Define which variant of elastic stack to use. (default: `elastic`)
 * *elastic_ca_dir*: Directory where on the Elasticsearch CA host certificates are stored. This is only useful in connection with out other Elastic Stack related roles. (default: `/opt/es-ca`)
 * *elastic_ca_pass*: Password for Elasticsearch CA (default: `PleaseChangeMe`)
@@ -102,17 +104,17 @@ If you want to use this role with your own TLS certificates, use these variables
 * *beats_tls_key_passphrase*: Passphrase of the keyfile (default: `ChangeMe`)
 * *beats_tls_cacert*: Path to the CA.crt (default: `{{ beats_ca_dir }}/ca.crt`)
 
+## Usage
 
-Dependencies
-------------
-
-None yet
-
-Example Playbook
-----------------
-
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
-
-    - hosts: servers
-      roles:
-         - { role: username.rolename, x: 42 }
+```
+- name: Install Elastic Beats
+  hosts: beats-hosts
+  collections:
+    - NETWAYS.elasticstack
+  vars:
+    elasticsearch_jna_workaround: true
+    elasticsearch_disable_systemcallfilterchecks: true
+  roles:
+    - repos
+    - beats
+```
diff --git a/docs/role-elasticsearch.md b/docs/role-elasticsearch.md
@@ -1,14 +1,11 @@
 ELASTICSEARCH
 =========
 
-This role installs Elasticsearch on your hosts. Optionally it can configure Elastics Security components, too.
+![Test Role Elasticsearch](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_elasticsearch.yml/badge.svg)
 
-If you use the role to set up security you can use its CA to create certificates for Logstash and Kibana, too.
-
-Requirements
-------------
+This role installs manages Elasticsearch on your hosts. Optionally it can configure Elastics Security components, too.
 
-Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+If you use the role to set up security you can use its CA to create certificates for Logstash and Kibana, too.
 
 Role Variables
 --------------
@@ -30,17 +27,16 @@ These variables are identical over all our elastic related roles, hence the diff
 * *elastic_release*: Major release version of Elastic stack to configure. (default: `7`)
 * *elastic_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`)
 
-
-Dependencies
-------------
-
-A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
-
-Example Playbook
-----------------
-
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
-
-    - hosts: servers
-      roles:
-         - { role: username.rolename, x: 42 }
+```
+- name: Install Elasticsearch
+  collections:
+    - NETWAYS.elasticstack
+  hosts: elasticsearch-hosts
+  vars:
+    elastic_variant: oss
+    elasticsearch_jna_workaround: true
+    elasticsearch_disable_systemcallfilterchecks: true
+  roles:
+    - repos
+    - elasticsearch
+```
diff --git a/docs/role-kibana.md b/docs/role-kibana.md
@@ -1,14 +1,10 @@
 Ansible Role: Kibana
 =========
 
-[![Molecule Tests](https://github.com/widhalmt/ansible-role-kibana/workflows/Molecule%20Test/badge.svg?event=push)](https://github.com/widhalmt/ansible-role-kibana/workflows/Molecule%20Test/badge.svg)
+![Test Role Kibana](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_kibana.yml/badge.svg)
 
 This roles installs and configures Kibana.
 
-Requirements
-------------
-
-You need to have the Elastic Repos configured on you system. You can use our [role](https://github.com/widhalmt/ansible-role-elastic-repos) for that but you don't have to.
 
 Role Variables
 --------------
@@ -34,22 +30,17 @@ These variables are identical over all our elastic related roles, hence the diff
 
 If you use `localhost` in `kibana_elasticsearch_hosts` , certificate verification will skip hostname checks
 
-Dependencies
-------------
-
-There's no real dependency but you might want to use this role together with our other Elastic Stack related roles:
-
-* [Elasticsearch](https://github.com/widhalmt/ansible-role-elasticsearch)
-* [Logstash](https://github.com/NETWAYS/ansible-role-logstash)
-* [Elastic Repositories](https://github.com/widhalmt/ansible-role-elastic-repos)
-
-Example Playbook
-----------------
-
-    - hosts: kibana
-      roles:
-         - kibana
-
-
-
-This role was created in 2019 by [Netways](https://www.netways.de/).
+## Usage
+
+```
+- name: Install Kibana
+  collections:
+    - NETWAYS.elasticstack
+  hosts: kibana-host
+  vars:
+    elastic_stack_full_stack: true
+    elastic_variant: oss
+  roles:
+    - repos
+    - kibana
+```
diff --git a/docs/role-logstash.md b/docs/role-logstash.md
@@ -1,7 +1,7 @@
 Ansible Role: Logstash
 =========
 
-[![CI](https://github.com/NETWAYS/ansible-role-logstash/workflows/Molecule%20Test/badge.svg?event=push)](https://github.com/NETWAYS/ansible-role-logstash/workflows/Molecule%20Test/badge.svg)
+![Test Role Logstash](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_logstash.yml/badge.svg)
 
 This role installs and configures [Logstash](https://www.elastic.co/products/logstash) on Linux systems.
 
@@ -18,7 +18,7 @@ Requirements
 
 * `community.general` collection
 
-You need to have the Elastic Repos configured on your system. You can use our [role](https://github.com/widhalmt/ansible-role-elastic-repos) for that but you don't have to.
+You need to have the Elastic Repos configured on your system. You can use our [role](./role-repos.md)
 
 If you want to use the default pipeline configuration you need to have `git` available.
 
@@ -85,21 +85,14 @@ The following variables only apply if you use this role together with our Elasti
 * *elastic_ca_dir*: Directory where the CA and certificates lie on the main Elasticsearch host (default: `/opt/es-ca`)
 * *elastic_initial_passwords*: File where initial passwords are stored on the main Elasticsearch host (default: `/usr/share/elasticsearch/initial_passwords`)
 
-Dependencies
-------------
-
-This role has no dependencies. As mentioned above you might want to use another role to install Redis
-
-Example Playbook
-----------------
-
-This is a simple sample playbook which first uses an Ansible role to install Redis and afterwards install and configure Logstash.
-
-    - hosts: logstash
-      roles:
-        - geerlingguy.redis
-        - logstash
-
-
-
-This role was created in 2019 by [Netways](https://www.netways.de/).
+## Usage
+
+```
+- name: Install Logstash
+  hosts: logstash-host
+  collections:
+    - NETWAYS.elasticstack
+  roles:
+    - repos
+    - logstash
+```