README.rst

==================================
aodh
==================================

Aodh is an alarming service for OpenStack. It used to be a part of Ceilometer, but starting from Mitaka it
is a separate project. Aodh supports several types of alarms like threshold, event, composite and gnocchi-specific.
In cluster mode, coordination is enabled via tooz with Redis backend.
MySQL is used as a data backend for alarms and alarm history.

Sample pillars
==============

Cluster aodh service

.. code-block:: yaml

    aodh:
      server:
        enabled: true
        version: mitaka
        ttl: 86400
        cluster: true
        enable_proxy_headers_parsing: True
        database:
          engine: "mysql+pymysql"
          host: 10.0.106.20
          port: 3306
          name: aodh
          user: aodh
          password: password
        bind:
          host: 10.0.106.20
          port: 8042
        identity:
          engine: keystone
          host: 10.0.106.20
          port: 35357
          tenant: service
          user: aodh
          password: password
        message_queue:
          engine: rabbitmq
          port: 5672
          user: openstack
          password: password
          virtual_host: '/openstack'
        cache:
          members:
          - host: 10.10.10.10
              port: 11211
          - host: 10.10.10.11
              port: 11211
          - host: 10.10.10.12
              port: 11211

Setting alarm history cleanup

In order to allow alarm cleanup from one node of the cluster,
server:role field should be set to primary and all others to
secondaey to avoid race conditions. On the example below
expirer is set to run every day at 2:00 AM. By default
it will be run every hour.

.. code-block:: yaml

    aodh:
      server:
        role: primary
        expirer:
          cron:
            minute: 0
            hour: 2

Enhanced logging with logging.conf
----------------------------------

By default logging.conf is disabled.

That is possible to enable per-binary logging.conf with new variables:
  * openstack_log_appender - set it to true to enable log_config_append for all OpenStack services;
  * openstack_fluentd_handler_enabled - set to true to enable FluentHandler for all Openstack services.
  * openstack_ossyslog_handler_enabled - set to true to enable OSSysLogHandler for all Openstack services.

Only WatchedFileHandler, OSSysLogHandler and FluentHandler are available.

Also it is possible to configure this with pillar:

.. code-block:: yaml

  aodh:
    server:
      logging:
        log_appender: true
        log_handlers:
          watchedfile:
            enabled: true
          fluentd:
            enabled: true
          ossyslog:
            enabled: true

Enable x509 and ssl communication between Aodh and Galera cluster.
---------------------
By default communication between Aodh and Galera is unsecure.

aodh:
  server:
    database:
      x509:
        enabled: True

You able to set custom certificates in pillar:

aodh:
  server:
    database:
      x509:
        cacert: (certificate content)
        cert: (certificate content)
        key: (certificate content)

You can read more about it here:
    https://docs.openstack.org/security-guide/databases/database-access-control.html

Aodh server with memcached caching and security strategy:

.. code-block:: yaml

    aodh:
      server:
        enabled: true
        ...
        cache:
          engine: memcached
          members:
          - host: 127.0.0.1
            port: 11211
          - host: 127.0.0.1
            port: 11211
          security:
            enabled: true
            strategy: ENCRYPT
            secret_key: secret

Setup redis coordination_backend url:
---------------------------
.. code-block:: yaml

    aodh:
      server:
        coordination_backend:
          engine: redis
          redis:
            password: pswd
            user: openstack
            db: '0'
            sentinel:
              host: 127.0.0.1
              master_name: master_1
              fallback:
                - host: 127.0.1.1
                - host: 127.0.2.1

Change default options using configmap template settings
========================================================

.. code-block:: yaml

    aodh:
      server:
        configmap:
          DEFAULT:
            rest_notifier_max_retries: 0
            notifier_topic: alarming
          api:
            user_alarm_quota: 10
            project_alarm_quota: 10
            alarm_max_actions: -1


Change files/directories permissions for aodh service:
=======================================
In order to change file permissions the following should be set:

'files' - block to set permissions for files.
- full path to file
- user ( default value is 'root' ) this parameter is optional.
- group ( default value is 'aodh' ) this parameter is optional
- mode ( default value is '0640' ) this parameter is optional

'directories' - block to set permissions for directories.
- full path to directory
- user ( default value is 'root' ) this parameter is optional
- group ( default value is 'aodh' ) this parameter is optional
- mode ( default value is '0750' ) this parameter is optional

.. code-block:: yaml

    aodh:
      files:
        /etc/aodh/aodh.conf:
          user: 'root'
          group: 'aodh'
          mode: '0750'
      directories:
        /etc/aodh:
          user: 'root'
          group: 'aodh'
          mode: '0750'




Development and testing
=======================

Development and test workflow with `Test Kitchen <http://kitchen.ci>`_ and
`kitchen-salt <https://github.com/simonmcc/kitchen-salt>`_ provisioner plugin.

Test Kitchen is a test harness tool to execute your configured code on one or more platforms in isolation.
There is a ``.kitchen.yml`` in main directory that defines *platforms* to be tested and *suites* to execute on them.

Kitchen CI can spin instances locally or remote, based on used *driver*.
For local development ``.kitchen.yml`` defines a `vagrant <https://github.com/test-kitchen/kitchen-vagrant>`_ or
`docker  <https://github.com/test-kitchen/kitchen-docker>`_ driver.

To use backend drivers or implement your CI follow the section `INTEGRATION.rst#Continuous Integration`__.

The `Busser <https://github.com/test-kitchen/busser>`_ *Verifier* is used to setup and run tests
implementated in `<repo>/test/integration`. It installs the particular driver to tested instance
(`Serverspec <https://github.com/neillturner/kitchen-verifier-serverspec>`_,
`InSpec <https://github.com/chef/kitchen-inspec>`_, Shell, Bats, ...) prior the verification is executed.

Usage:

.. code-block:: shell

  # list instances and status
  kitchen list

  # manually execute integration tests
  kitchen [test || [create|converge|verify|exec|login|destroy|...]] [instance] -t tests/integration

  # use with provided Makefile (ie: within CI pipeline)
  make kitchen



Read more
=========

* https://docs.openstack.org/cli-reference/aodh.html
* https://docs.openstack.org/developer/aodh/