104 lines
5.0 KiB
ReStructuredText
104 lines
5.0 KiB
ReStructuredText
..
|
|
Copyright 2015 IBM Corp.
|
|
All Rights Reserved.
|
|
|
|
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.
|
|
|
|
Versioned Objects
|
|
=================
|
|
|
|
Magnum uses the `oslo.versionedobjects library
|
|
<http://docs.openstack.org/developer/oslo.versionedobjects/index.html>`_ 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
|
|
<http://docs.openstack.org/developer/oslo.versionedobjects/api/fixture.html#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
|
|
(Container 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 = {'Container': '1.0-e12affbba5f8a748882a3ae98aced282'}
|
|
actual = {'Container': '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 Container means I need
|
|
to bump the version of Container, so I increase the version and add a comment
|
|
saying what I changed in the new version::
|
|
|
|
@base.MagnumObjectRegistry.register
|
|
class Container(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 = {'Container': '1.0-e12affbba5f8a748882a3ae98aced282'}
|
|
actual = {'Container': '1.1-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.
|
|
|
|
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 = {
|
|
'Bay': '1.0-35edde13ad178e9419e7ea8b6d580bcd',
|
|
'BayModel': '1.0-06863f04ab4b98307e3d1b736d3137bf',
|
|
'Container': '1.1-22b40e8eed0414561ca921906b189820',
|
|
'MyObj': '1.0-b43567e512438205e32f4e95ca616697',
|
|
'Pod': '1.0-69b579203c6d726be7878c606626e438',
|
|
'ReplicationController': '1.0-782b7deb9307b2807101541b7e58b8a2',
|
|
'Service': '1.0-d4b8c0f3a234aec35d273196e18f7ed1',
|
|
'X509KeyPair': '1.0-fd008eba0fbc390e0e5da247bba4eedd',
|
|
}
|
|
|
|
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.
|