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/ directory (managed by the debops.secret role) to autorize 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.

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
      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' ]

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.