magnum/doc/source/objects.rst

Versioned Objects

Magnum uses the oslo.versionedobjects library to construct an object model that can be communicated via RPC. These objects have a version history and functionality to convert from one version to a previous version. This allows for 2 different levels of the code to still pass objects to each other, as in the case of rolling upgrades.

Object Version Testing

In order to ensure object versioning consistency is maintained, oslo.versionedobjects has a fixture to aid in testing object versioning. oslo.versionedobjects.fixture.ObjectVersionChecker generates fingerprints of each object, which is a combination of the current version number of the object, along with a hash of the RPC-critical parts of the object (fields and remotable methods).

The tests hold a static mapping of the fingerprints of all objects. When an object is changed, the hash generated in the test will differ from that held in the static mapping. This will signal to the developer that the version of the object needs to be increased. Following this version increase, the fingerprint that is then generated by the test can be copied to the static mapping in the tests. This symbolizes that if the code change is approved, this is the new state of the object to compare against.

Object Change Example

The following example shows the unit test workflow when changing an object (Cluster was updated to hold a new 'foo' field):

tox -e py27 magnum.tests.unit.objects.test_objects

This results in a unit test failure with the following output:

testtools.matchers._impl.MismatchError: !=:
reference = {'Cluster': '1.0-35edde13ad178e9419e7ea8b6d580bcd'}
actual    = {'Cluster': '1.0-22b40e8eed0414561ca921906b189820'}

: Fields or remotable methods in some objects have changed. Make sure the versions of the objects has been bumped, and update the hashes in the static fingerprints tree (object_data). For more information, read http://docs.openstack.org/developer/magnum/objects.html.

This is an indication that me adding the 'foo' field to Cluster means I need to bump the version of Cluster, so I increase the version and add a comment saying what I changed in the new version:

@base.MagnumObjectRegistry.register
class Cluster(base.MagnumPersistentObject, base.MagnumObject,
              base.MagnumObjectDictCompat):
    # Version 1.0: Initial version
    # Version 1.1: Added 'foo' field
    VERSION = '1.1'

Now that I have updated the version, I will run the tests again and let the test tell me the fingerprint that I now need to put in the static tree:

testtools.matchers._impl.MismatchError: !=:
reference = {'Cluster': '1.0-35edde13ad178e9419e7ea8b6d580bcd'}
actual    = {'Cluster': '1.1-22b40e8eed0414561ca921906b189820'}

I can now copy the new fingerprint needed (1.1-22b40e8eed0414561ca921906b189820), to the object_data map within magnum/tests/unit/objects/test_objects.py:

object_data = {
    'Cluster': '1.1-22b40e8eed0414561ca921906b189820',
    'ClusterTemplate': '1.0-06863f04ab4b98307e3d1b736d3137bf',
    'Certificate': '1.0-69b579203c6d726be7878c606626e438',
    'MyObj': '1.0-b43567e512438205e32f4e95ca616697',
    'X509KeyPair': '1.0-fd008eba0fbc390e0e5da247bba4eedd',
    'MagnumService': '1.0-d4b8c0f3a234aec35d273196e18f7ed1',
}

Running the unit tests now shows no failure.

If I did not update the version, and rather just copied the new hash to the object_data map, the review would show the hash (but not the version) was updated in object_data. At that point, a reviewer should point this out, and mention that the object version needs to be updated.

If a remotable method were added/changed, the same process is followed, because this will also cause a hash change.