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)** diff --git a/roles/kibana/README.md b/roles/kibana/README.md new file mode 100644 index 00000000..c0fb1153 --- /dev/null +++ b/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. + + +## 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, 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. | + + + +## 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). diff --git a/roles/kibana/meta/argument_specs.yml b/roles/kibana/meta/argument_specs.yml new file mode 100644 index 00000000..4794dbed --- /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, 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.