From f35b5dec940b9f36bd57751468c3545fb3026a68 Mon Sep 17 00:00:00 2001 From: Vincent Francoise Date: Fri, 7 Oct 2016 14:51:12 +0200 Subject: [PATCH] Specs for watcher-versioned-objects This changeset introduces that changes to be made in watcher-versioned-objects. Change-Id: I3d8b16e6d89542aa2ac08649b0806d9eefd118a8 Partially-Implements: blueprint watcher-versioned-objects --- .../approved/watcher-versioned-objects.rst | 203 ++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 specs/ocata/approved/watcher-versioned-objects.rst diff --git a/specs/ocata/approved/watcher-versioned-objects.rst b/specs/ocata/approved/watcher-versioned-objects.rst new file mode 100644 index 00000000..53a13cf5 --- /dev/null +++ b/specs/ocata/approved/watcher-versioned-objects.rst @@ -0,0 +1,203 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +============================== +Make Watcher objects versioned +============================== + +https://blueprints.launchpad.net/watcher/+spec/watcher-versioned-objects + +As we are making Watcher more stable, we now have to tackle the +question of retro-compatibility. Other OpenStack projects already faced this +problem and the community came up with a common answer which is object +versioning. + +Below is a non-exhaustive list of blueprint specifications written on the +subject by other projects: + + - https://specs.openstack.org/openstack/oslo-specs/specs/kilo/adopt-oslo-versionedobjects.html + - https://specs.openstack.org/openstack/heat-specs/specs/kilo/versioned-objects.html + + +Problem description +=================== + +As of now, Watcher maintains some (but not all) building blocks previously used +by other projects such as Nova in order to enable the versioning of objects. +As Watcher is now part of the Big Tent, we should start taking into account +backwards compatibility. Moreover, we should standardize the code and therefore +make use of `oslo.versionedobjects`_. + +.. _oslo.versionedobjects: http://docs.openstack.org/developer/oslo.versionedobjects/ + +Use Cases +--------- + +Whenever existing Watcher objects are created or modified or deleted, the +concerned Watcher objects should see their version bumped whilst indicating +the changes that occurred in order to ease retro-compatibility handling +throughout the codebase. + + +Proposed change +=============== + +The focus of this blueprint is to rewrite the Watcher codebase implements its +objects to leverage `oslo.versionedobjects`_ library to enable the versioning +of Watcher objects. + +Besides, `oslo.versionedobjects`_ brings along many new field types, among +which ``ObjectField`` can be found. This field can reveal itself useful in +subsequent work about building versioned notifications as we will be most +certainly keen on notifying a more complete set of information that would also +include some data that are directly related to the given Watcher object. +This work will hence be tackled within this blueprint. + +Alternatives +------------ + +- Keep the current codebase and enhance it to support some form of versioning +- Do not support any form of object versioning + +Data model impact +----------------- + +Add DB relationships on existing models wherever foreign key fields where +already defined: + +- The `Strategy`_ will have one ORM relationship field: + + * A ``goal`` field reflecting the ``goal_id`` ForeignKey field + +- The `AuditTemplate`_ will have two ORM relationship fields: + + * A ``goal`` field reflecting the ``goal_id`` ForeignKey field + * A ``strategy`` field reflecting the ``strategy_id`` ForeignKey field + +- The `Audit`_ will have two ORM relationship fields: + + * A ``goal`` field reflecting the ``goal_id`` ForeignKey field + * A ``strategy`` field reflecting the ``strategy_id`` ForeignKey field + +- The `ActionPlan`_ will have two ORM relationship fields: + + * A ``audit`` field reflecting the ``audit_id`` ForeignKey field + * A ``strategy`` field reflecting the ``strategy_id`` ForeignKey field + +- The `Action`_ will have one ORM relationship field: + + * An ``action_plan`` field reflecting the ``action_plan_id`` ForeignKey field + +- The `EfficacyIndicator`_ will have one ORM relationship field: + + * An ``action_plan`` field reflecting the ``action_plan_id`` ForeignKey field + +Moreover, unused DB fields will be removed in order to avoid non +retro-compatible changes as much as possible. + + +.. _Strategy: http://docs.openstack.org/developer/watcher/glossary.html#strategy +.. _AuditTemplate: http://docs.openstack.org/developer/watcher/glossary.html#audit-template +.. _Audit: http://docs.openstack.org/developer/watcher/glossary.html#audit +.. _ActionPlan: http://docs.openstack.org/developer/watcher/glossary.html#action-plan +.. _Action: http://docs.openstack.org/developer/watcher/glossary.html#action +.. _EfficacyIndicator: http://docs.openstack.org/developer/watcher/glossary.html#efficacy-indicator + + +REST API impact +--------------- + +The API design will not be impacted by the ``eager`` flag. +Indeed, API endpoints will not return any eagerly-loaded data. + +Security impact +--------------- + +None. + +Notifications impact +-------------------- + +This work will help building versioned notifications. + +Other end user impact +--------------------- + +None. + +Performance Impact +------------------ + +Loading ``ObjectField`` data makes queries slower. This is the reason why the +concept of eager loading is introduced alongside this blueprint to limit the +associated performance hit to areas where this eager loading is necessary. +Also note that this eager loading will not be cascaded which means that +eagerly loaded related objects will not be subject to eager loading themselves. + +Other deployer impact +--------------------- + +None. + +Developer impact +---------------- + +As objects are being versioned from now on, any modification of an existing +Watcher object should be directly translated into a version bump. +Retro-compatible changes should see the minor version of the related object +bumped whereas any disrupting changes should be translated by a transition to +a new major version. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + vincent-francoise + +Work Items +---------- + +Here below are the changes to be made: + +- Enable database loading of ORM relationships in the case of One-to-One and + One-to-Many foreign keys. +- Add the possibility to either eager load or not the newly added ORM + relationships for performance purposes. +- Overhaul the code in ``watcher/objects/base.py`` to now use + `oslo.versionedobjects`_. +- Update all Watcher objects which had foreign key fields to add + ``ObjectField`` fields that will have to be filled whenever an eager loading + of the underlying DB model is requested. + +Dependencies +============ + +None. + +Testing +======= + +Apart from updating existing unit test suites, this blueprint does not bring +any new end-user functionality. Hence, the current set of Tempest test should +remain unchanged and still pass upon completion. + +Documentation Impact +==================== + +The DB schema shown in the architecture will have to be updated. + +References +========== + +None. + +History +======= + +None.