-
Notifications
You must be signed in to change notification settings - Fork 0
Roles kibana
Ansible role for installing, configuring, and managing Kibana. Handles service management, TLS encryption for the Kibana web UI, Elasticsearch connection setup, and certificate management.
In a full-stack deployment, this role runs after elasticsearch. It connects to Elasticsearch using the elastic user password generated during security setup, and optionally serves the Kibana web UI over HTTPS with its own TLS certificate.
graph TD
A[Include shared defaults] --> B[Install package]
B --> C{Security enabled?}
C -->|Yes| D[Fetch cert from ES CA]
C -->|No| E[Write kibana.yml]
D --> F{Cert expiring?}
F -->|Yes| G[Regenerate cert]
F -->|No| E
G --> E
E --> H[Read elastic password<br/>from CA host]
H --> I[Start service]
I --> J[Wait for Kibana :5601]
J --> K([Done])
style D fill:#ffd700,stroke:#333
style H fill:#e8478b,stroke:#333,color:#fff
- Minimum Ansible version:
2.18 - The
elasticsearchrole must have completed (Kibana needs a running ES cluster to connect to)
Whether to enable and start the Kibana service.
kibana_enable: true # defaultLet the role manage kibana.yml. Set to false to manage the configuration file yourself.
kibana_manage_yaml: true # defaultCreate a backup of kibana.yml before overwriting.
kibana_config_backup: true # defaultEnable security features — connects to Elasticsearch over HTTPS with the elastic user credentials. When elasticstack_security is true, this is typically also true.
kibana_security: true # defaultDiscover all Elasticsearch nodes in the cluster on Kibana startup. Useful for multi-node ES clusters where Kibana should be aware of all nodes.
kibana_sniff_on_start: false # defaultRe-discover Elasticsearch nodes when a connection fault is detected. Helps Kibana recover automatically when an ES node goes down.
kibana_sniff_on_connection_fault: false # defaultThese settings control HTTPS on the Kibana frontend itself (what users access in their browser). This is separate from the TLS used to connect to Elasticsearch.
Enable TLS on the Kibana web interface (serve Kibana over HTTPS). When false, Kibana serves over plain HTTP on port 5601. You typically terminate TLS at a reverse proxy instead.
kibana_tls: false # defaultPath to the TLS certificate file for the Kibana web interface.
kibana_tls_cert: /etc/kibana/certs/cert.pem # defaultPath to the TLS private key file for the Kibana web interface.
kibana_tls_key: /etc/kibana/certs/key.pem # defaultPassphrase for the Kibana TLS private key.
kibana_tls_key_passphrase: PleaseChangeMe # defaultValidity period in days for generated TLS certificates. Default is 3 years.
kibana_cert_validity_period: 1095 # defaultDays before certificate expiry to trigger automatic renewal.
kibana_cert_expiration_buffer: 30 # defaultInternal flag set when certificates are within the expiration buffer. Do not set manually.
kibana_cert_will_expire_soon: false # defaultTracks whether this is a fresh installation. Do not set manually.
kibana_freshstart:
changed: falseThe role generates two persistent encryption keys on the CA host during security setup:
-
General encryption key (
xpack.security.encryptionKey) — used for session cookies and other security tokens -
Saved objects encryption key (
xpack.encryptedSavedObjects.encryptionKey) — used for encrypting saved objects like alert rules and connector credentials
Both keys are 36-byte base64 values generated with openssl rand and stored in {{ elasticstack_ca_dir }}/encryption_key and savedobjects_encryption_key. They use a creates: guard so they're generated once and never overwritten — losing these keys would invalidate all encrypted saved objects.
The role resolves ES hosts through a multi-level fallback:
- If
kibana_elasticsearch_hostsis explicitly set, use it - Otherwise, if the
elasticstack_elasticsearch_group_namegroup exists in inventory, build the host list from that group - If neither is available, fall back to
localhost
When Kibana connects to Elasticsearch on localhost, hostname verification would fail because the ES certificate contains the node's real hostname, not localhost. The template detects this and sets elasticsearch.ssl.verificationMode: certificate (verify the certificate chain only, skip hostname check). For non-localhost connections, full verification is used.
Kibana binds to 0.0.0.0 (all interfaces) by default. This is hardcoded in the template, not configurable via a variable. If you need to restrict binding, use kibana_extra_config:
kibana_extra_config: |
server.host: "127.0.0.1"If elasticstack_cert_pass is defined (a global cert passphrase), the role uses it as kibana_tls_key_passphrase instead of the role's own default. This lets you set a single passphrase for all roles.
The role waits for Kibana port 5601 with an explicit 300-second timeout. Kibana can take several minutes to start on first run (especially on low-memory hosts) as it creates system indices and generates browser bundles. Without the explicit timeout, Ansible's wait_for module could hang indefinitely in some environments.
The "Restart Kibana" handler does not fire on fresh installs (kibana_freshstart.changed guard). On a first run, the service starts naturally during the "Start Kibana" task — a handler restart would be redundant and could cause a brief outage during initial index creation.
During certificate renewal, the role backs up the existing certificate to three locations before replacing it:
- On the Kibana node itself (
/etc/kibana/certs/) - On the CA host (the P12 file used to generate the cert)
- On the Ansible controller (fetched copy)
This provides recovery options if renewal causes issues.
In container environments, the role runs rm -rf /var/cache/* after starting Kibana. This frees disk space so Elasticsearch can allocate replicas of the .security-7 index (which requires >85% free disk by default, or >97% with the role's lenient watermarks).
| Tag | Purpose |
|---|---|
certificates |
Run all certificate-related tasks |
renew_ca |
Renew the certificate authority |
renew_kibana_cert |
Renew only the Kibana certificate |
GPL-3.0-or-later
Netways GmbH