vitrage-specs/specs/stein/implemented/parametrized_template.rst

Parametrized Template

StoryBoard link: https://storyboard.openstack.org/#!/story/2004056

This spec suggests a method to quickly create Vitrage templates based on a template that contains parameters.

Problem description

Vitrage template language is powerful, yet a bit verbose and it's quite easy to make syntax mistakes when creating a new template from scratch. Moreover, in real production environments, we see that many templates have a very similar structure like "an alarm on a host is propagated to its instances". We would like to make it easier to generate the most common templates.

Another motivation for this feature is for Heat usage. A Heat user should be able to easily define a Vitrage template for auto-healing or auto-scaling its stack based on specific alarms. For more information, see Heat_spec and Heat_template.

Proposed change

Parts of a template, like alarm names, resource states, etc. can be written as parameters. When creating a new template, the user will have to assign actual values to each parameter that doesn't have a default value. The concept is similar to the way that parameters are used in Heat.

A Parameters section can be added to standard templates. Each parameter will hold two optional fields:

• description
• default

All values will be strings.

The parameters can be used inside the templates, using a get_param(param) syntax.

Vitrage template add API will include a new option to create a template based on a template with parameters. The template will be added to the database only if all parameters are set.

Example for a template with parameters

metadata:
  version: 2
  type: standard
  name: host_affects_instance_prototype
  description: Template prototype for scenarios where a Zabbix alarm on a host affects its instances
parameters:
  host_alarm_rawtext:
    description: Zabbix rawtext of the alarm on the host
  instance_alarm_name:
    description: Name of the alarm to be created on the instance
  instance_alarm_severity:
    description: Severity of the alarm to be created on the instance
    default: WARNING
  host_state:
    description: New state to be set for the host
    default: SUBOPTIMAL
  instance_state:
    description: New state to be set for the instance
    default: SUBOPTIMAL
definitions:
  entities:
   - entity:
      category: ALARM
      type: zabbix
      rawtext: get_param(host_alarm_rawtext)
      template_id: host_alarm
   - entity:
      category: ALARM
      type: vitrage
      name: get_param(instance_alarm_name)
      template_id: instance_alarm
   - entity:
      category: RESOURCE
      type: nova.instance
      template_id: instance
   - entity:
      category: RESOURCE
      type: nova.host
      template_id: host
  relationships:
   - relationship:
      source: host_alarm
      relationship_type: on
      target: host
      template_id : alarm_on_host
   - relationship:
      source: host
      relationship_type: contains
      target: instance
      template_id : host_contains_instance
   - relationship:
      source: instance_alarm
      relationship_type: on
      target: instance
      template_id : alarm_on_instance
scenarios:
  - scenario:
     condition: alarm_on_host and host_contains_instance
     actions:
      - action:
          action_type: raise_alarm
          action_target:
            target: instance
          properties:
            alarm_name: get_param(instance_alarm_name)
            severity: get_param(instance_alarm_severity)
      - action:
          action_type: set_state
          action_target:
            target: instance
          properties:
            state: get_param(instance_state)
  - scenario:
     condition: alarm_on_host and host_contains_instance and alarm_on_instance
     actions:
      - action:
          action_type: add_causal_relationship
          action_target:
            source: host_alarm
            target: instance_alarm
  - scenario:
     condition: alarm_on_host
     actions:
      - action:
          action_type: set_state
          action_target:
            target: host
          properties:
            state: SUBOPTIMAL

CLI Example

vitrage template add --path ./host_affects_instance_prototype.yaml --param 'host_alarm_rawtext'='High CPU load on host' --param 'instance_alarm_name'='High CPU load on instance'

Or:

vitrage template add --path ./host_affects_instance_prototype.yaml --params 'host_alarm_rawtext'='High CPU load on host', 'instance_alarm_name'='High CPU load on instance'

Alternatives

Hold a template prototype catalog

Define templates of type prototype that will be added to Vitrage database like other templates, but will be ignored by the evaluator.

There will be APIs to:

• Add a template prorotype
• View all template prototypes
• Add a template based on an existing prototype name

Advantages:

• At runtime, Vitrage will hold a template prototype catalog that can be used by the end users.

Disadvantages:

• Since users will not add new templates very often, the advantage is not very important.
• It will be harder to use the prototype ability in Heat, since the HOT template will have to depend on runtime information of Vitrage.
• We will have to decide how to handle prototype updates. The same HOT template will behave differently if the prototype in Vitrage has changed.

Implement this feature in Heat

Instead of adding template prototypes in Vitrage, the prototyping option can be quite easily implemented in Heat. The main disadvantage is, of course, that the feature will not be available in Vitrage.

The entire Vitrage template can be written inside a Hot template, in one of two ways:

1. As part of the Vitrage Template resource in Heat. The disadvantage is that the Heat resource will be tightly coupled with Vitrage, and any syntax change in Vitrage should be reflected in Heat.
2. As a comment inside the Vitrage Template resource in Heat. The disadvantage is that writing a long yaml file as a comment is less clear and may result in syntax and alignment errors.

Data model impact

None. The template parameters will be given actual values, and standard templates will be added to the database.

REST API impact

Parameters should be added to vitrage template add function call, if the path points to a template with parameters . All parameters that are required in the template must be set.

There will be two ways to specify the parameters:

• param: Followed by a key=value pair. There can be few param pairs.
• params: Followed by a list of key=value parameters, separated by ",".

Versioning impact

These changes will be part of Vitrage template version 3.

Other end user impact

None

Deployer impact

None

Developer impact

None

Horizon impact

None. In the future this feature may be used to write a template editor UI.

Implementation

Assignee(s)

Primary assignee:

ifat_afek

Work Items

• Introduce Vitrage template version 3
• Support template loading and parameters injection for template parameters
• Support template validation for templates with parameters
• New parameters for template add API
• Documentation and tests

Dependencies

None

Testing

Unit tests, functional tests and tempest tests

Documentation Impact

The new template format will be documented

References

None