..
      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.
      Convention for heading levels in collectd-ceilometer-plugin documentation:

      =======  Heading 0 (reserved for the title in a document)
      -------  Heading 1
      ~~~~~~~  Heading 2
      +++++++  Heading 3
      '''''''  Heading 4

      Avoid deeper levels because they do not render well.

===========================================================
Instructions for enabling auto-scaling using heat templates
===========================================================

This is a guide that provides instructions on how to create a heat template to
enable auto-scaling of a cloud application based on alarms. To make use of the
metrics generated by the gnocchi plugin, a heat template can be created that
will auto-scale a user defined resource based on Aodh alarms. These alarms can
monitor the new metrics generated by the plugins. The template will outline the
infrastructure of the desired cloud application, as well as the resources that
will trigger and monitor the scaling feature, i.e. the alarms, groups and
policies.

.. note::

       The collectd-gnocchi plugin only supports certain types of Aodh alarms.
       Please find a list of these options in:

https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/alarms_guide.rst


Creating a heat template for auto-scaling
-----------------------------------------

Please follow the steps below to create a heat template that enables auto-scaling:

1. The instructions outlined in the link below will enable you to create a
   simple template that will define your resource, i.e. the cloud application,
   that you want to scale, e.g. OS::Nova::Server.
   https://docs.openstack.org/heat/latest/template_guide/hot_guide.html

2. Define the scaling group for the above resource that you want to scale. At a
   minimum the "desired_capacity", the "min_size" and the "max_size" and the
   resource itself has to be specified.
   For more information on this resource:
   https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Heat::AutoScalingGroup

  ::

     group:
       type: OS::Heat::AutoScalingGroup


3. Specify the policies that will be applied if an alarm is triggered.
   Depending on the type of alarm that will be used to trigger these policies
   a separate policy can be defined for each alarm state; "alarm", "ok" and
   "insufficient data".
   For more information on this resource:
   https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Heat::ScalingPolicy

  ::

     policy:
       type: OS::Heat::ScalingPolicy


4. Define the alarm/s that will trigger the scaling, follow the
   instructions for the relevant plugins in the final two sections of
   this guide.

5. Create your heat stack using this template that you have written.
   Run the following command:

  ::

    heat stack create -t <TEMPLATE_NAME.yml> <STACK_NAME>


Verification of Stack Creation and Scaling
------------------------------------------

To verify that your stack has been created run the following command;

  ::

    heat stack list


The status of the stack should be "CREATE_COMPLETE". This means that all
of the resources defined within the template have been created. To confirm
this check the event list of the stack:

  ::

    heat stack event list <STACK_NAME>


Additionally, this command will allow you to observe whether the alarm you
have defined has changed state and if it has scaled your cloud application
resource accordingly.
Alternatively you can monitor the state of your alarm by running:

  ::

    aodh alarm list


If you defined an OS::Nova::Server as your application, then you can check if
it has scaled up/down via:

  ::

    openstack server list


collectd-gnocchi-plugin alarms
------------------------------

The alarms available for this plugin are defined in alarms_guide.rst.
To create a "gnocchi_aggregation_by_metrics_alarm" in a heat template define an
OS::Aodh::GnocchiAggregationByMetricsAlarm resource.
Define this resource with the metric/s from the gnocchi plugin and the
threshold you want the alarm to be triggered on.
For more information on this resource:
https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Aodh::GnocchiAggregationByMetricsAlarm

  ::

    gnocchi_alarm:
      type: OS::Aodh::GnocchiAggregationByMetricsAlarm

Please find a sample template for this type here:
https://github.com/openstack/collectd-ceilometer-plugin/tree/master/doc/source/examples/templates/metrics.yml.
Adjust variables accordingly to suit your environment.