76057450b5
- Fix erros when run tox -edocs (except one spec - cinder-integration.rst, will be fixed when merge patch set [1]) - Update urls. [1] https://review.openstack.org/#/c/468658/ Change-Id: I05865708ef356f17a388eace234ac004dd1a364f
121 lines
5.1 KiB
ReStructuredText
121 lines
5.1 KiB
ReStructuredText
..
|
|
|
|
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
|
|
<https://docs.openstack.org/oslo.versionedobjects/latest/>`_ 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
|
|
<https://docs.openstack.org/oslo.versionedobjects/latest/reference/fixture.html#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:
|
|
|
|
.. code-block:: python
|
|
|
|
testtools.matchers._impl.MismatchError: !=:
|
|
reference = {'Container': '1.0-35edde13ad178e9419e7ea8b6d580bcd'}
|
|
actual = {'Container': '1.0-22b40e8eed0414561ca921906b189820'}
|
|
|
|
.. code-block:: console
|
|
|
|
: 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:
|
|
|
|
.. code-block:: python
|
|
|
|
@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:
|
|
|
|
.. code-block:: python
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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.
|