From da0eae45bd567ffdabb3a45d9d861de5daac6a55 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 1 Jul 2026 17:10:18 +0200 Subject: [PATCH 1/6] add meta/argument_specs.yml for all role variables --- roles/kibana/meta/argument_specs.yml | 124 +++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 roles/kibana/meta/argument_specs.yml diff --git a/roles/kibana/meta/argument_specs.yml b/roles/kibana/meta/argument_specs.yml new file mode 100644 index 00000000..700f2659 --- /dev/null +++ b/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). 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 Kibana certificate. 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. From 2be0bee8eaea33470bfa174111956885d0b63ed7 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 1 Jul 2026 17:12:35 +0200 Subject: [PATCH 2/6] add README generated from argument_specs --- roles/kibana/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 roles/kibana/README.md diff --git a/roles/kibana/README.md b/roles/kibana/README.md new file mode 100644 index 00000000..8f718c8f --- /dev/null +++ b/roles/kibana/README.md @@ -0,0 +1,62 @@ +# Ansible Role: Kibana + +Installs and configures [Kibana](https://www.elastic.co/kibana) on Linux systems. +The role can manage `kibana.yml`, the connection to Elasticsearch, TLS for the +Kibana server, and — in a full stack setup — the X-Pack security certificates. + +## Requirements + +* The Elastic repositories configured — use the [`repos`](../repos) role. +* A reachable Elasticsearch instance for Kibana to connect to. + +## 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. + + +## Role variables + +| 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). 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 Kibana certificate. 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. | + + + +## 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). From abfcca4234208094975a2044d38defd3b23840cd Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 1 Jul 2026 17:19:53 +0200 Subject: [PATCH 3/6] - Point docs to the role README - Skip the kibana role molecule for docs-only changes --- .github/workflows/test_role_kibana.yml | 1 + README.md | 2 +- docs/getting-started.md | 2 +- docs/role-kibana.md | 59 ++------------------------ 4 files changed, 6 insertions(+), 58 deletions(-) diff --git a/.github/workflows/test_role_kibana.yml b/.github/workflows/test_role_kibana.yml index ae9058de..15a2fc8a 100644 --- a/.github/workflows/test_role_kibana.yml +++ b/.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_**' diff --git a/README.md b/README.md index f4252d72..2d4c4e10 100644 --- a/README.md +++ b/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) diff --git a/docs/getting-started.md b/docs/getting-started.md index dc49fb40..a9c63295 100644 --- a/docs/getting-started.md +++ b/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) diff --git a/docs/role-kibana.md b/docs/role-kibana.md index f1df2640..bddfb880 100644 --- a/docs/role-kibana.md +++ b/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)** From cc9ba6bd4ec9d98b2d6552e1fdee8bf1027c9f7d Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Wed, 1 Jul 2026 17:31:26 +0200 Subject: [PATCH 4/6] clarify kibana_tls_key_passphrase and kibana_sniff_interval descriptions --- roles/kibana/README.md | 4 ++-- roles/kibana/meta/argument_specs.yml | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/roles/kibana/README.md b/roles/kibana/README.md index 8f718c8f..fb6e0591 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -40,11 +40,11 @@ Run only parts of the role with `--tags`: | `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). Unset by default. | +| `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 Kibana certificate. Overridden by elasticstack_cert_pass when that is set. | +| `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. | diff --git a/roles/kibana/meta/argument_specs.yml b/roles/kibana/meta/argument_specs.yml index 700f2659..4794dbed 100644 --- a/roles/kibana/meta/argument_specs.yml +++ b/roles/kibana/meta/argument_specs.yml @@ -64,7 +64,7 @@ argument_specs: kibana_sniff_interval: type: str - description: Interval between sniffing attempts (elasticsearch.sniffInterval). Unset by default. + description: Interval between sniffing attempts (elasticsearch.sniffInterval, in milliseconds). Unset by default. # ----- Kibana server TLS ----- kibana_tls: @@ -86,8 +86,8 @@ argument_specs: type: str default: PleaseChangeMe description: >- - Passphrase for the Kibana certificate. Overridden by elasticstack_cert_pass - when that is set. + 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: From ff0e63207aa3a66dbab60389d90855866ad8b318 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Thu, 2 Jul 2026 15:45:06 +0200 Subject: [PATCH 5/6] Note that browser TLS certificates are user-provided --- roles/kibana/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/roles/kibana/README.md b/roles/kibana/README.md index fb6e0591..1b82faa5 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -8,6 +8,9 @@ Kibana server, and — in a full stack setup — the X-Pack security certificate * 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 From a1ab416199700579dddfbf058f2bb7f5e34e6672 Mon Sep 17 00:00:00 2001 From: Afeef Ghannam Date: Fri, 3 Jul 2026 10:01:16 +0200 Subject: [PATCH 6/6] Update the certificate info in readme --- roles/kibana/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/roles/kibana/README.md b/roles/kibana/README.md index 1b82faa5..c0fb1153 100644 --- a/roles/kibana/README.md +++ b/roles/kibana/README.md @@ -1,8 +1,10 @@ # Ansible Role: Kibana Installs and configures [Kibana](https://www.elastic.co/kibana) on Linux systems. -The role can manage `kibana.yml`, the connection to Elasticsearch, TLS for the -Kibana server, and — in a full stack setup — the X-Pack security certificates. +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