vitrage-specs/specs/mitaka/nova-entity-transformer.rst

Nova Entity Transformer

https://blueprints.launchpad.net/vitrage/+spec/nova-entity-transformer

When an entity event is being introduced into Vitrage graph, it must be transformed into a type which can be handled by the graph. The Entity transformer is responsible for converting an entity event into entity wrapper. Each entity type has his own transformer.

All transformers should be written in python and added to vitrage.conf. The Entity Transformer Engine allows a service provider to extend support for other entities by writing a designated transformer for each entity type.

The first transformers to implement are:

• Nova Instance transformer
• Nova Host transformer

Problem description

In Vitrage graph, each (instance of an) entity is represented as a vertex. Therefore, the output of a transformer is a vertex for the given entity (an "entity vertex"). In addition, the transformer also returns a list of (vertex, edge)-pairs. The vertex in each pair describes a neighbor with limited properties, and the edge represents the connection between both vertices, describing their relationship.

There are different Entity Types that should be supported by Vitrage:

• Openstack types (Nova.instance, Nova.host and etc.)
• Non-Openstack types (Nagios tests, Physical resources and etc.)

Note: in Vitrage Graph, each vertex contains a dictionary of key-value pairs which represents the entity properties. Similarly, each edge contains a dictionary of key-value pairs which represents aspects of the relation between two vertices.

Proposed change

When the Entity Processor receives a new entity event, it asks the Entity Transformer to convert the event into an object which the processor can then enter into the Vitrage Graph.

Transformer Operation: When receiving an entity event, the Transformer Engine first recognizes the entity type and accordingly activates the corresponding transformer. Each transformer inherits from the Transformer base class and implements the three methods:

• Method that returns an entity wrapper
• Method that returns key fields and their order.The key fields are mandatory
• Method that returns a key by given an entity event

Output Object

The transformer returns an Entity Wrapper, which is a tuple containing an entity vertex and a list of (vertex,edge) pairs that describe the entity neighbors (relationships).

Entity (source) vertex description:

Mandatory properties:

• key - For Openstack entities this is the Openstack ID. For non-Openstack

  entities this is an ID which will generated by Vitrage

• Type - Resource Physical Resource Alarm Tests Results
• Sub Type - Alarm Name, host, instance, switch and etc.
• Entity Name

• Is Deleted- needed for graph maintenance and marks items that can be

  gathered by the garbage collector

Optional properties (vertex metadata)

• State
• Project ID

The optional properties list is flexible and can be changed as needed. In addition, each entity type can have its own relevant properties.

(vertex, edge) Pairs:

The pair describes a entity’s neighbor vertex and their relationship. Relationships can be both physical, virtual or (in the future) logical

Target vertex description:

The vertex in the pair must have sufficient data to help specify uniquely which vertex in the Vitrage Graph will be connected to this entity. Currently, the minimal information needed for this is:

• ID - For each entity, must have the data which vertex it connects
• Type - Resource Physical Resource Alarm Tests Results
• Sub Type - Alarm Name, host, instance, switch and etc.

Edge description:

• Source ID Entity ID
• Target ID - For each entity, must have the data which vertex it connects
• Relation Type - contains, run, attached and etc.

Event Type:

The type of the event as it happened. Possible options:

• CREATE - New entity is created
• UPDATE - The entity has been updated
• DELETE - When the entity is deleted

Alternatives

None

Data model impact

TBD

REST API impact

None

Versioning impact

None

Other end user impact

None

Deployer impact

TBD

Developer impact

TBD

Horizon impact

None

Implementation

Assignee(s)

liat har-tal

Work Items

None

Dependencies

None

Testing

All code will be tested

Documentation Impact

None

References

Vitrage project <https://wiki.openstack.org/wiki/Vitrage>