Getting started¶
Upstream package is used by default¶
The Debian and Ubuntu archives contain the elasticsearch
packages, however
they are very old releases (1.x). The security support for the package in Debian has been discontinued
due to issues with upstream security policy (Debian Bug #803713).
Debian Developers suggest that in production environments the upstream version should be used
to provide adequate security updates.
Due to the above reasons, the role is focused on the upstream Kibana release
only (5.x+) to keep compatibility with upstream Elasticsearch. The package
installation itself is handled by the debops.elastic_co
Ansible role which
also manages upstream APT repository configuration.
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.
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:
- import_role:
name: 'kibana'
tasks_from: 'main_env'
tags: [ 'role::kibana', 'role::secret', 'role::kibana:config' ]
roles:
- role: keyring
tags: [ 'role::keyring', 'skip::keyring', 'role::nginx', 'role::elastic_co' ]
keyring__dependent_apt_keys:
- '{{ nginx__keyring__dependent_apt_keys }}'
- '{{ elastic_co__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:
- '{{ elastic_co__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: elastic_co
tags: [ 'role::elastic_co', 'skip::elastic_co' ]
elastic_co__dependent_packages:
- '{{ kibana__elastic_co__dependent_packages }}'
- role: kibana
tags: [ 'role::kibana', 'skip::kibana' ]
Ansible tags¶
You can use Ansible --tags
or --skip-tags
parameters to limit what
tasks are performed during Ansible run. This can be used after a host was first
configured to speed up playbook execution, when you are sure that most of the
configuration is already in the desired state.
Available role tags:
role::kibana
- Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.
role::kibana:config
- Generate the Kibana configuration taking into account different configuration sources.