zun/doc/source/contributor/objects.rst

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

Zun 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 (Container was updated to hold a new 'foo' field):

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

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

testtools.matchers._impl.MismatchError: !=:
reference = {'Container': '1.0-35edde13ad178e9419e7ea8b6d580bcd'}
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 https://docs.openstack.org/zun/latest/.

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.ZunObjectRegistry.register
class Container(base.ZunPersistentObject, base.ZunObject,
              base.ZunObjectDictCompat):
    # Version 1.0: Initial version
    # Version 1.1: Add container_id column
    # Version 1.2: Add memory column
    # Version 1.3: Add task_state column
    # Version 1.4: Add cpu, workdir, ports, hostname and labels columns
    # Version 1.5: Add meta column
    # Version 1.6: Add addresses column
    # Version 1.7: Add host column
    # Version 1.8: Add restart_policy
    # Version 1.9: Add status_detail column
    # Version 1.10: Add tty, stdin_open
    # Version 1.11: Add image_driver
    VERSION = '1.11'

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.10-35edde13ad178e9419e7ea8b6d580bcd'}
actual    = {'Container': '1.11-ddffeb42cb5472decab6d73534fe103f'}

I can now copy the new fingerprint needed (1.11-ddffeb42cb5472decab6d73534fe103f), to the object_data map within zun/tests/unit/objects/test_objects.py:

object_data = {
    'Container': '1.11-ddffeb42cb5472decab6d73534fe103f',
    'Image': '1.0-0b976be24f4f6ee0d526e5c981ce0633',
    'NUMANode': '1.0-cba878b70b2f8b52f1e031b41ac13b4e',
    'NUMATopology': '1.0-b54086eda7e4b2e6145ecb6ee2c925ab',
    'ResourceClass': '1.0-2c41abea55d0f7cb47a97bdb345b37fd',
    'ResourceProvider': '1.0-92b427359d5a4cf9ec6c72cbe630ee24',
    'ZunService': '1.0-2a19ab9987a746621b2ada02d8aadf22',
}

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.