.. 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/meters generated by the ceilometer and gnocchi plugins, 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/meters 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-ceilometer and collectd-gnocchi plugins only support 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/developer/heat/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/developer/heat/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/developer/heat/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 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 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-ceilometer-plugin alarms --------------------------------- As described in alarms_guide.rst, this plugin allows you to create Aodh threshold alarms. This type of alarm can be defined in a heat template using an OS::Aodh::Alarm resource. Define this resource with the ceilometer meter that you want to monitor and the threshold you want the alarm to be triggered at. For more information on this resource: https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Aodh::Alarm :: threshold_alarm: type: OS::Aodh::Alarm Please find a sample template for this type here: https://github.com/openstack/collectd-ceilometer-plugin/tree/master/doc/source/examples/templates/threshold.yml. Adjust variables accordingly to suit your environment. collectd-gnocchi-plugin alarms ------------------------------ Again, 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/developer/heat/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.