Kibana role docs

.github/workflows/test_role_kibana.yml

@@ -15,6 +15,7 @@ on:
   pull_request:
     paths:
       - 'roles/kibana/**'
+      - '!roles/kibana/**/*.md'
       - '.github/workflows/test_role_kibana.yml'
       - 'molecule/kibana_**'
 

README.md

@@ -14,7 +14,7 @@ Every role is documented with all variables, please refer to the documentation f
 
 * [Beats](docs/role-beats.md)
 * [Elasticsearch](docs/role-elasticsearch.md)
-* [Kibana](docs/role-kibana.md)
+* [Kibana](roles/kibana/README.md)
 * [Logstash](roles/logstash/README.md)
 * [Repos](docs/role-repos.md)
 

docs/getting-started.md

@@ -49,7 +49,7 @@ Roles
 
 * [Beats](role-beats.md)
 * [Elasticsearch](role-elasticsearch.md)
-* [Kibana](role-kibana.md)
+* [Kibana](../roles/kibana/README.md)
 * [Logstash](../roles/logstash/README.md)
 * [Repos](role-repos.md)
 

docs/role-kibana.md

@@ -1,58 +1,5 @@
-Ansible Role: Kibana
-=========
+# Kibana role
 
-![Test Role Kibana](https://github.com/netways/ansible-collection-elasticstack/actions/workflows/test_role_kibana.yml/badge.svg)
+The Kibana role documentation now lives with the role itself:
 
-This roles installs and configures Kibana.
-
-Role Variables
---------------
-
-* *kibana_manage_yaml*: Change Kibanas main configuration file (default: `true`)
-* *kibana_config_backup*: Keep backups if we change any configuration file (default: `true`)
-* *kibana_tls*: Whether to offer `https` for clients or not (default: `false`)
-* *kibana_tls_cert*: Path to the certificate Kibana should show to its clients (default: `/etc/kibana/certs/cert.pem`)
-* *kibana_tls_key*: Path to the key Kibana should use when communicating with clients (default: `/etc/kibana/certs/key.pem`)
-* *kibana_extra_config*: You can add arbitraty configuration options with this option. Just start it with `|-` and indent the following lines. So you can add as many lines and options to `kibana.yml` as you like. (default: none)
-
-* *kibana_security*: Activate TLS and authentication when connecting to Elasticsearch. **Note**: Only works when `elasticstack_full_stack` is enabled. (default: `true`)
-
-These variables are identical over all our elastic related roles, hence the different naming scheme.
-
-* *elasticstack_full_stack*: Use `ansible-role-elasticsearch` as well (default: `false`). If you set to `true`, you will be able to use the following variables:
-    * *kibana_elasticsearch_hosts*: A list of DNS resolvable hostnames of Elasticsearch hosts to connect your Kibana instance to. (default: `- localhost`)
-    * *elasticstack_elasticsearch_http_port*: Port of Elasticsearch http (Default: `9200`)
-    * *kibana_sniff_on_start*: Attempt to find other Elasticsearch nodes on startup (default: `false`)
-    * *kibana_sniff_on_connection_fault* Update the list of Elasticsearch nodes immediately following a connection fault (default: `false`)
-    * *kibana_sniff_interval*: Time in milliseconds between requests to check Elasticsearch for an updated list of nodes (default: `not set`)
-
-* *kibana_tls_key_passphrase*: Passphrase for kibana certificates (default: `PleaseChangeMe`)
-* *kibana_cert_validity_period*: number of days that the generated certificates are valid (default: 1095).
-* *kibana_cert_expiration_buffer*: Ansible will renew the kibana certificate if its validity is shorter than this value, which should be number of days. (default: 30)
-* *kibana_cert_will_expire_soon*: Set it to true to renew kibana certificate (default: `false`), Or run the playbook with `--tags renew_kibana_cert` to do that.
-* *elasticstack_kibana_host*: Hostname users use to connect to Kibana (default: FQDN of the host the role is executed on)
-* *elasticstack_kibana_port*: Port Kibana webinterface is listening on (default: `5601`)
-* *elasticstack_ca_host*: Set to the inventory hostname of the host that should house the CA for certificates for inter-node communication. (default: First node in the `elasticsearch` host group)
-* *elasticstack_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`)
-* *elasticstack_ca_pass*: Password for Elasticsearch CA (default: `PleaseChangeMe`)
-* *elasticstack_initial_passwords*: Path to file with initical elasticsearch passwords (default: `/usr/share/elasticsearch/initial_passwords`)
-* *elasticstack_release*: Major release version of Elastic stack to configure. (default: `7`)
-* *elasticstack_variant*: Variant of the stack to install. Valid values: `elastic` or `oss` (default: `elastic`)
-
-
-If you use `localhost` in `kibana_elasticsearch_hosts` , certificate verification will skip hostname checks
-
-## Usage
-
-```
-- name: Install Kibana
-  collections:
-    - netways.elasticstack
-  hosts: kibana-host
-  vars:
-    elasticstack_full_stack: true
-    elasticstack_variant: oss
-  roles:
-    - repos
-    - kibana
-```
+**➜ [roles/kibana/README.md](../roles/kibana/README.md)**

roles/kibana/README.md

@@ -0,0 +1,67 @@
+# 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.
+
+## Requirements
+
+* The Elastic repositories configured — use the [`repos`](../repos) role.
+* 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
+
+```yaml
+- name: Install Kibana
+  hosts: kibana
+  collections:
+    - netways.elasticstack
+  roles:
+    - repos
+    - kibana
+```
+
+## Tags
+
+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.
+
+<!-- ANSIBLE DOCSMITH MAIN START -->
+## Role variables<a id="variables"></a>
+
+| Variable | Type | Default | Choices | Description |
+|----------|------|---------|---------|-------------|
+| `kibana_enable` | `bool` | `true` | — | Start and enable the Kibana service. |
+| `kibana_config_backup` | `bool` | `true` | — | Keep a backup of kibana.yml whenever the role changes it. |
+| `kibana_manage_yaml` | `bool` | `true` | — | Manage and overwrite kibana.yml. |
+| `kibana_elasticsearch_hosts` | `list` of `str` | N/A | — | Elasticsearch hosts Kibana connects to. Defaults to the nodes from the elasticsearch group, or localhost when used standalone. |
+| `kibana_security` | `bool` | `true` | — | Enable X-Pack security: connect to Elasticsearch over HTTPS with authentication and set up the encryption keys. Only effective in a full stack setup with the elastic variant. |
+| `kibana_sniff_on_start` | `bool` | `false` | — | Ask Elasticsearch for the list of nodes at startup (elasticsearch.sniffOnStart). |
+| `kibana_sniff_on_connection_fault` | `bool` | `false` | — | Update the list of Elasticsearch nodes on connection fault (elasticsearch.sniffOnConnectionFault). |
+| `kibana_sniff_interval` | `str` | N/A | — | Interval between sniffing attempts (elasticsearch.sniffInterval, in milliseconds). Unset by default. |
+| `kibana_tls` | `bool` | `false` | — | Enable TLS on the Kibana server itself (server.ssl). |
+| `kibana_tls_cert` | `str` | `"/etc/kibana/certs/cert.pem"` | — | Path to the certificate for the Kibana server TLS. |
+| `kibana_tls_key` | `str` | `"/etc/kibana/certs/key.pem"` | — | Path to the private key for the Kibana server TLS. |
+| `kibana_tls_key_passphrase` | `str` | `"PleaseChangeMe"` | — | Passphrase for the generated Kibana security certificate (X-Pack, full stack). Overridden by elasticstack_cert_pass when that is set. |
+| `kibana_cert_validity_period` | `int` | `1095` | — | Number of days the generated certificates are valid. |
+| `kibana_cert_expiration_buffer` | `int` | `30` | — | Renew the certificate when its remaining validity (in days) drops below this value. |
+| `kibana_cert_will_expire_soon` | `bool` | `false` | — | Set to true to force renewal of the Kibana certificate. Alternatively run the playbook with the renew_kibana_cert tag. |
+| `kibana_extra_config` | `str` | N/A | — | Extra configuration appended verbatim to kibana.yml (YAML). Unset by default. |
+| `kibana_freshstart` | `dict` | `{'changed': False}` | — | Internal state used by the role to detect a fresh install. Do not set manually. |
+
+<!-- ANSIBLE DOCSMITH MAIN END -->
+
+## Shared variables
+
+This role also uses the collection-wide `elasticstack_*` variables (e.g.
+`elasticstack_full_stack`, `elasticstack_variant`, `elasticstack_release`,
+`elasticstack_ca_host`, `elasticstack_ca_pass`, `elasticstack_kibana_host`,
+`elasticstack_kibana_port`, `elasticstack_elasticsearch_http_port`). They are
+documented centrally with the [elasticsearch role](../../docs/role-elasticsearch.md).

roles/kibana/meta/argument_specs.yml

@@ -0,0 +1,124 @@
+---
+# Role argument specification for the kibana role.
+# This is the single source of truth for the role's variables: Ansible validates
+# the supplied values against it at role start, and ansible-docsmith renders the
+# README variable reference and the comments in defaults/main.yml from it.
+#
+# Only kibana_* variables live here. The shared elasticstack_* variables are
+# documented centrally with the elasticstack role.
+
+argument_specs:
+  main:
+    short_description: Install and configure Kibana
+    description:
+      - Installs and configures Kibana on Linux systems.
+      - >-
+        Can manage kibana.yml, the connection to Elasticsearch, TLS for the
+        Kibana server, and the X-Pack security certificates.
+    author:
+      - NETWAYS GmbH
+
+    options:
+
+      # ----- Service & general -----
+      kibana_enable:
+        type: bool
+        default: true
+        description: Start and enable the Kibana service.
+
+      kibana_config_backup:
+        type: bool
+        default: true
+        description: Keep a backup of kibana.yml whenever the role changes it.
+
+      kibana_manage_yaml:
+        type: bool
+        default: true
+        description: Manage and overwrite kibana.yml.
+
+      # ----- Elasticsearch connection -----
+      kibana_elasticsearch_hosts:
+        type: list
+        elements: str
+        description: >-
+          Elasticsearch hosts Kibana connects to. Defaults to the nodes from the
+          elasticsearch group, or localhost when used standalone.
+
+      kibana_security:
+        type: bool
+        default: true
+        description: >-
+          Enable X-Pack security: connect to Elasticsearch over HTTPS with
+          authentication and set up the encryption keys. Only effective in a full
+          stack setup with the elastic variant.
+
+      kibana_sniff_on_start:
+        type: bool
+        default: false
+        description: Ask Elasticsearch for the list of nodes at startup (elasticsearch.sniffOnStart).
+
+      kibana_sniff_on_connection_fault:
+        type: bool
+        default: false
+        description: Update the list of Elasticsearch nodes on connection fault (elasticsearch.sniffOnConnectionFault).
+
+      kibana_sniff_interval:
+        type: str
+        description: Interval between sniffing attempts (elasticsearch.sniffInterval, in milliseconds). Unset by default.
+
+      # ----- Kibana server TLS -----
+      kibana_tls:
+        type: bool
+        default: false
+        description: Enable TLS on the Kibana server itself (server.ssl).
+
+      kibana_tls_cert:
+        type: str
+        default: /etc/kibana/certs/cert.pem
+        description: Path to the certificate for the Kibana server TLS.
+
+      kibana_tls_key:
+        type: str
+        default: /etc/kibana/certs/key.pem
+        description: Path to the private key for the Kibana server TLS.
+
+      kibana_tls_key_passphrase:
+        type: str
+        default: PleaseChangeMe
+        description: >-
+          Passphrase for the generated Kibana security certificate (X-Pack, full
+          stack). Overridden by elasticstack_cert_pass when that is set.
+
+      # ----- Security certificates (X-Pack, full stack) -----
+      kibana_cert_validity_period:
+        type: int
+        default: 1095
+        description: Number of days the generated certificates are valid.
+
+      kibana_cert_expiration_buffer:
+        type: int
+        default: 30
+        description: >-
+          Renew the certificate when its remaining validity (in days) drops below
+          this value.
+
+      kibana_cert_will_expire_soon:
+        type: bool
+        default: false
+        description: >-
+          Set to true to force renewal of the Kibana certificate. Alternatively
+          run the playbook with the renew_kibana_cert tag.
+
+      # ----- Extra configuration -----
+      kibana_extra_config:
+        type: str
+        description: >-
+          Extra configuration appended verbatim to kibana.yml (YAML). Unset by
+          default.
+
+      # ----- Internal -----
+      kibana_freshstart:
+        type: dict
+        default:
+          changed: false
+        description: Internal state used by the role to detect a fresh install. Do not set manually.