Skip to content

Commit 2117988

Browse files
mkayontourmkayontour
authored
Doc/update documentation (#3)
* update docs * add info about the collection * added examples * cleanup galaxy.yml * remove commentary
1 parent a158609 commit 2117988

9 files changed

+203
-152
lines changed

Diff for: ‎AUTHORS

+1
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ Nathaniel Donahue <[email protected]>
77
Patrick Dolinic <[email protected]>
88
Shittu Ayomide <[email protected]>
99
Thomas Widhalm <[email protected]>
10+
Thilo Wening <[email protected]>

Diff for: ‎README.md

+37-2
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,46 @@
11
# Ansible Collection - netways.elasticstack
22

3-
Documentation for the collection.
3+
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)**
44

5-
## Roles
5+
6+
7+
## Roles Documentation
68

79
* [Beats](docs/role-beats.md)
810
* [Elasticsearch](docs/role-elasticsearch.md)
911
* [Kibana](docs/role-kibana.md)
1012
* [Logstash](docs/role-logstash.md)
1113
* [Repos](docs/role-repos.md)
14+
15+
## Installation
16+
17+
You can easily install the collection with the ansible-galaxy command.
18+
19+
```
20+
ansible-galaxy collection install netways.elasticstack
21+
```
22+
23+
Or if you are using Tower or AWX add the collection to your requirements file.
24+
25+
```
26+
collections:
27+
- name: netways.elasticstack
28+
```
29+
30+
## Usage
31+
32+
```
33+
- name: Install Elasticsearch
34+
hosts: all
35+
collections:
36+
- NETWAYS.elasticstack
37+
vars:
38+
elastic_variant: oss
39+
elasticsearch_jna_workaround: true
40+
roles:
41+
- repos
42+
- beats
43+
- elasticsearch
44+
- logstash
45+
- kibana
46+
```

Diff for: ‎docs/getting-started.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
Collection Elastic Stack
2+
-------------------------
3+
4+
Installation
5+
-----------
6+
7+
You can easily install the collection with the ansible-galaxy command.
8+
9+
```
10+
ansible-galaxy collection install netways.elasticstack
11+
```
12+
13+
Or if you are using Tower or AWX add the collection to your requirements file.
14+
15+
```
16+
collections:
17+
- name: NETWAYS.elasticstack
18+
```
19+
20+
Usage
21+
---------
22+
23+
To use the collection in your Ansible playbook add the following key to your playbook.
24+
25+
```
26+
- name: Playbook
27+
hosts: some_host_pattern
28+
collections:
29+
- NETWAYS.elasticstack
30+
tasks:
31+
- name: import role logstash
32+
import_role:
33+
name: logstash
34+
```
35+
36+
Or refer to the role with the FQCN of the role.
37+
38+
```
39+
- name: Playbook
40+
hosts: some_host_pattern
41+
tasks:
42+
- name: import role by FQCN from a collection
43+
import_role:
44+
name: NETWAYS.elasticstack.logstash
45+
```
46+
47+
Roles
48+
-------
49+
50+
* [Beats](docs/role-beats.md)
51+
* [Elasticsearch](docs/role-elasticsearch.md)
52+
* [Kibana](docs/role-kibana.md)
53+
* [Logstash](docs/role-logstash.md)
54+
* [Repos](docs/role-repos.md)
55+
56+
57+
Variables
58+
-----------
59+
60+
Every role got its own set of variables, in addition a few variables are useable on any role. Below are all general collection vars.
61+
62+
* *elastic_release*: Major release version of Elastic stack to configure. (default: `7`)
63+
* *elastic_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`)

Diff for: ‎docs/role-beats.md

+22-20
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
Ansible Role: Beats
22
=========
33

4-
[![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)
4+
![Test Role Beats](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_beats.yml/badge.svg)
55

66
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.
77

88
Requirements
99
------------
1010

11-
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.
11+
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.
1212

1313
Role Variables
1414
--------------
1515

1616
* *beats_filebeat*: Install and manage filebeat (Default: `true`)
17-
* *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`)
17+
* *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`)
1818
* *filebeat_enable*: Automatically start Filebeat (Default: `true`)
1919
* *filebeat_output*: Set to `logstash` or `elasticsearch`. (default: `logstash`)
2020
* *filebeat_syslog_udp*: Use UDP Syslog input (Default: `false`)
@@ -26,12 +26,14 @@ Role Variables
2626
* *filebeat_log_inputs*: Logfiles to read (Default: see below)
2727

2828
Default of `filebeat_log_inputs`
29+
2930
```
3031
messages:
3132
name: messages
3233
paths:
3334
- /var/log/messages
3435
```
36+
3537
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)
3638

3739
Here's a longer example for an input:
@@ -51,7 +53,7 @@ filebeat_log_inputs:
5153
```
5254
* *filebeat_journald*: Enable collection of JournalD logs (default: `false`) - available since Filebeat 7.16
5355
* *filebeat_journald_inputs*: List of journald inputs. Use for different filters on events. You can add a list of `include_matches` entries for filtering.
54-
Default of `filebeat_journald_inputs:
56+
Default of `filebeat_journald_inputs`:
5557
```
5658
filebeat_journald_inputs:
5759
everything:
@@ -63,14 +65,14 @@ filebeat_journald_inputs:
6365
* *filebeat_loadbalance*: Enable loadbalancing for Filebeats Logstash output (default: `true`)
6466

6567
* *beats_auditbeat*: Install and manage filebeat (Default: `false`)
66-
* *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`)
68+
* *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`)
6769
* *auditbeat_output*: Output for Auditbeat Set to `logstash` or `elasticsearch`. (default: `elasticsearch`)
6870
* *auditbeat_enable*: Automatically start Auditbeat (Default: `true`)
6971
* *auditbeat_setup*: Run Auditbeat Setup (Default: `true`) (Only works with Elasticsearch output)
7072
* *auditbeat_loadbalance*: Enable loadbalancing for Auditbeats Logstash output (default: `true`)
7173

7274
* *beats_metricbeat*: Enable installation and management of Metricbeat (Default: `false`)
73-
* *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`)
75+
* *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`)
7476
* *metricbeat_enable*: Start Metricbeat automatically (Default: `true`)
7577
* *metricbeat_output*: Set to `logstash` or `elasticsearch`. (default: `elasticsearch`)
7678
* *metricbeat_modules*: List of modules to enable. (Default: `- system`)
@@ -88,7 +90,7 @@ filebeat_journald_inputs:
8890

8991
The following variables only apply if you use this role together with our other Elastic Stack roles.
9092

91-
* *elastic_stack_full_stack*: Use `ansible-role-elasticsearch` as well (default: `false`)
93+
* *elastic_stack_full_stack*: Use `elasticsearch` as well (default: `false`)
9294
* *elastic_variant*: Define which variant of elastic stack to use. (default: `elastic`)
9395
* *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`)
9496
* *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
102104
* *beats_tls_key_passphrase*: Passphrase of the keyfile (default: `ChangeMe`)
103105
* *beats_tls_cacert*: Path to the CA.crt (default: `{{ beats_ca_dir }}/ca.crt`)
104106

107+
## Usage
105108

106-
Dependencies
107-
------------
108-
109-
None yet
110-
111-
Example Playbook
112-
----------------
113-
114-
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
115-
116-
- hosts: servers
117-
roles:
118-
- { role: username.rolename, x: 42 }
109+
```
110+
- name: Install Elastic Beats
111+
hosts: beats-hosts
112+
collections:
113+
- NETWAYS.elasticstack
114+
vars:
115+
elasticsearch_jna_workaround: true
116+
elasticsearch_disable_systemcallfilterchecks: true
117+
roles:
118+
- repos
119+
- beats
120+
```

Diff for: ‎docs/role-elasticsearch.md

+16-20
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
11
ELASTICSEARCH
22
=========
33

4-
This role installs Elasticsearch on your hosts. Optionally it can configure Elastics Security components, too.
4+
![Test Role Elasticsearch](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_elasticsearch.yml/badge.svg)
55

6-
If you use the role to set up security you can use its CA to create certificates for Logstash and Kibana, too.
7-
8-
Requirements
9-
------------
6+
This role installs manages Elasticsearch on your hosts. Optionally it can configure Elastics Security components, too.
107

11-
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.
8+
If you use the role to set up security you can use its CA to create certificates for Logstash and Kibana, too.
129

1310
Role Variables
1411
--------------
@@ -30,17 +27,16 @@ These variables are identical over all our elastic related roles, hence the diff
3027
* *elastic_release*: Major release version of Elastic stack to configure. (default: `7`)
3128
* *elastic_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`)
3229

33-
34-
Dependencies
35-
------------
36-
37-
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.
38-
39-
Example Playbook
40-
----------------
41-
42-
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
43-
44-
- hosts: servers
45-
roles:
46-
- { role: username.rolename, x: 42 }
30+
```
31+
- name: Install Elasticsearch
32+
collections:
33+
- NETWAYS.elasticstack
34+
hosts: elasticsearch-hosts
35+
vars:
36+
elastic_variant: oss
37+
elasticsearch_jna_workaround: true
38+
elasticsearch_disable_systemcallfilterchecks: true
39+
roles:
40+
- repos
41+
- elasticsearch
42+
```

Diff for: ‎docs/role-kibana.md

+15-24
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
11
Ansible Role: Kibana
22
=========
33

4-
[![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)
4+
![Test Role Kibana](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_kibana.yml/badge.svg)
55

66
This roles installs and configures Kibana.
77

8-
Requirements
9-
------------
10-
11-
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.
128

139
Role Variables
1410
--------------
@@ -34,22 +30,17 @@ These variables are identical over all our elastic related roles, hence the diff
3430

3531
If you use `localhost` in `kibana_elasticsearch_hosts` , certificate verification will skip hostname checks
3632

37-
Dependencies
38-
------------
39-
40-
There's no real dependency but you might want to use this role together with our other Elastic Stack related roles:
41-
42-
* [Elasticsearch](https://github.com/widhalmt/ansible-role-elasticsearch)
43-
* [Logstash](https://github.com/NETWAYS/ansible-role-logstash)
44-
* [Elastic Repositories](https://github.com/widhalmt/ansible-role-elastic-repos)
45-
46-
Example Playbook
47-
----------------
48-
49-
- hosts: kibana
50-
roles:
51-
- kibana
52-
53-
54-
55-
This role was created in 2019 by [Netways](https://www.netways.de/).
33+
## Usage
34+
35+
```
36+
- name: Install Kibana
37+
collections:
38+
- NETWAYS.elasticstack
39+
hosts: kibana-host
40+
vars:
41+
elastic_stack_full_stack: true
42+
elastic_variant: oss
43+
roles:
44+
- repos
45+
- kibana
46+
```

Diff for: ‎docs/role-logstash.md

+13-20
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Ansible Role: Logstash
22
=========
33

4-
[![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)
4+
![Test Role Logstash](https://github.com/NETWAYS/ansible-collection-elasticstack/actions/workflows/test_role_logstash.yml/badge.svg)
55

66
This role installs and configures [Logstash](https://www.elastic.co/products/logstash) on Linux systems.
77

@@ -18,7 +18,7 @@ Requirements
1818

1919
* `community.general` collection
2020

21-
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.
21+
You need to have the Elastic Repos configured on your system. You can use our [role](./role-repos.md)
2222

2323
If you want to use the default pipeline configuration you need to have `git` available.
2424

@@ -85,21 +85,14 @@ The following variables only apply if you use this role together with our Elasti
8585
* *elastic_ca_dir*: Directory where the CA and certificates lie on the main Elasticsearch host (default: `/opt/es-ca`)
8686
* *elastic_initial_passwords*: File where initial passwords are stored on the main Elasticsearch host (default: `/usr/share/elasticsearch/initial_passwords`)
8787

88-
Dependencies
89-
------------
90-
91-
This role has no dependencies. As mentioned above you might want to use another role to install Redis
92-
93-
Example Playbook
94-
----------------
95-
96-
This is a simple sample playbook which first uses an Ansible role to install Redis and afterwards install and configure Logstash.
97-
98-
- hosts: logstash
99-
roles:
100-
- geerlingguy.redis
101-
- logstash
102-
103-
104-
105-
This role was created in 2019 by [Netways](https://www.netways.de/).
88+
## Usage
89+
90+
```
91+
- name: Install Logstash
92+
hosts: logstash-host
93+
collections:
94+
- NETWAYS.elasticstack
95+
roles:
96+
- repos
97+
- logstash
98+
```

0 commit comments

Comments
 (0)