Getting started
Upstream package is used by default
The debops.kibana role depends on the debops.extrepo Ansible role to configure access to the Elastic.co APT repository. This means that usually the latest available Kibana release will be installed by default. If you require older releases, you can use the debops.apt_preferences role to select the desired package version.
Alternatively, you can "mask" the
kibana__extrepo__dependent_sources
variable in the Ansible
inventory and configure the APT repositories yourself via the debops.apt
role.
Kibana is insecure by default
The Kibana dashboard relies on Elasticsearch to ensure secure communication between cluster nodes. The default configuration expects an Elasticsearch instance installed on the same host, preferably in a "load balancer" mode, that is with no master possibility, no data or ingest functions enabled on the node.
Kibana by default does not include any authentication or ACL support; however
the role by default does not configure any access restrictions. If you want to
have a simple security solution, you can use kibana__webserver_*
variables
to configure HTTP Basic Auth in the nginx frontend. Keep in mind
that once a user is authenticated using this method, he/she has full access to
the Elasticsearch cluster.
If the first host used for connections to the Elasticsearch cluster uses
a https://
connection, Kibana will try to use the kibana_system
Elasticsearch user account and password stored in the
secret/elasticsearch/credentials/<cluster_name>/built-in/kibana_system/password
file (managed by the debops.secret role) to authorize itself with the
cluster and set up its own configuration. After that, you can use other users
(notably elastic
superuser account) to access the web interface.
Note
Make sure that the Elasticsearch cluster name specified via the
elasticsearch__cluster_name
variable is synchronized with
the kibana__elasticsearch_cluster_name
variable in the
inventory. Otherwise, the debops.kibana role might not find
the correct password file and will not connect with the Elasticsearch
cluster.
The reason for doing it this way is that Kibana can be installed separately from Elasticsearch (on separate hosts), and there's no way for the debops.kibana role to find out the correct cluster name on its own, if it's not the default.
You can install additional plugins that provide encrypted connections, authentication, authorization and access control:
X-Pack, an Elastic commercial plugin with free trial period. Supports encryption, authentication, access control, integrates with Elasticsearch and Logstash. Since the plugin is developed by the same team, its releases are in parallel with Kibana.
Search Guard, an open source third party plugin with commercial support. Has features comparable with X-Pack, with more basic features like HTTP and transport encryption, basic authentication and access control available free of charge.
Use as a role dependency
The Kibana main configuration file
does not support an include statement or conf.d directory.
To mitigate that and allow multiple Kibana configuration sources from other
Ansible roles, the debops.kibana
role supports operation as a dependent
role. This functionality can be used by other Ansible roles to better manage
Kibana plugins or extend the configuration without the need to implement the
entire role again and with preserved idempotency.
See the Usage as a role dependency for more details.
Example inventory
To deploy Kibana, you can add the host to the
[debops_service_kibana]
Ansible inventory group. By default Kibana expects
an Elasticsearch instance on the same host to leverage the cluster load
balancing. To install an ES node in a load balancer configuration, include the
host in the [debops_service_elasticsearch_lb]
inventory group:
[debops_service_kibana]
hostname
[debops_service_elasticsearch_lb]
hostname
See the documentation of the debops.elasticsearch
role about different
Ansible inventory group types and their usage.
Example playbook
If you are using this role without DebOps, here's an example Ansible playbook
that uses the debops.kibana
role:
---
- name: Manage Kibana service
collections: [ 'debops.debops', 'debops.roles01',
'debops.roles02', 'debops.roles03' ]
hosts: [ 'debops_service_kibana' ]
become: True
environment: '{{ inventory__environment | d({})
| combine(inventory__group_environment | d({}))
| combine(inventory__host_environment | d({})) }}'
pre_tasks:
- name: Prepare kibana environment
ansible.builtin.import_role:
name: 'kibana'
tasks_from: 'main_env'
tags: [ 'role::kibana', 'role::secret', 'role::kibana:config' ]
roles:
- role: extrepo
tags: [ 'role::extrepo', 'skip::extrepo', 'role::kibana' ]
extrepo__dependent_sources:
- '{{ kibana__extrepo__dependent_sources }}'
- role: keyring
tags: [ 'role::keyring', 'skip::keyring', 'role::nginx', 'role::elastic_co' ]
keyring__dependent_apt_keys:
- '{{ nginx__keyring__dependent_apt_keys }}'
- role: secret
tags: [ 'role::secret', 'role::kibana', 'role::kibana:config' ]
secret__directories:
- '{{ kibana__secret__directories }}'
- role: apt_preferences
tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
apt_preferences__dependent_list:
- '{{ nginx__apt_preferences__dependent_list }}'
- role: etc_services
tags: [ 'role::etc_services', 'skip::etc_services' ]
etc_services__dependent_list:
- '{{ kibana__etc_services__dependent_list }}'
- role: ferm
tags: [ 'role::ferm', 'skip::ferm' ]
ferm__dependent_rules:
- '{{ nginx__ferm__dependent_rules }}'
- role: python
tags: [ 'role::python', 'skip::python' ]
python__dependent_packages3:
- '{{ nginx__python__dependent_packages3 }}'
python__dependent_packages2:
- '{{ nginx__python__dependent_packages2 }}'
- role: nginx
tags: [ 'role::nginx', 'skip::nginx' ]
nginx__dependent_servers:
- '{{ kibana__nginx__dependent_servers }}'
nginx__dependent_upstreams:
- '{{ kibana__nginx__dependent_upstreams }}'
- role: kibana
tags: [ 'role::kibana', 'skip::kibana' ]