diff --git a/doc/source/index.rst b/doc/source/index.rst index 0785dfc..9a2c0f1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,6 +7,15 @@ Oslo Design Specifications ============================ +Victoria +======== + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/victoria/* + Ussuri ====== diff --git a/specs/victoria/oslo-vmware-soap-library-switch.rst b/specs/victoria/oslo-vmware-soap-library-switch.rst new file mode 100644 index 0000000..fb45b49 --- /dev/null +++ b/specs/victoria/oslo-vmware-soap-library-switch.rst @@ -0,0 +1,185 @@ +.. + This template should be in ReSTructured text. For help with syntax, + see http://sphinx-doc.org/rest.html + + To test out your formatting, build the docs using tox, or see: + http://rst.ninjs.org + + The filename in the git repository should match the launchpad URL, + for example a URL of + https://blueprints.launchpad.net/oslo?searchtext=awesome-thing should be + named awesome-thing.rst. + + For specs targeted at a single project, please prefix the first line + of your commit message with the name of the project. For example, + if you're submitting a new feature for oslo.config, your git commit + message should start something like: "config: My new feature". + + Wrap text at 79 columns. + + Do not delete any of the sections in this template. If you have + nothing to say for a whole section, just write: None + + If you would like to provide a diagram with your spec, ascii diagrams are + required. http://asciiflow.com/ is a very nice tool to assist with making + ascii diagrams. The reason for this is that the tool used to review specs is + based purely on plain text. Plain text will allow review to proceed without + having to look at additional files which can not be viewed in gerrit. It + will also allow inline feedback on the diagram itself. + +============================================ +Switching oslo.vmware's backing SOAP library +============================================ + +We want to switch the SOAP library used in olso.vmware to another library +(`zeep `_), because the +currently-used library (`suds-jurko `_) is +unmaintained, not compatible with Python 3.10 and lacks in performance. + +Problem description +=================== + +With Python 2 being removed from all of OpenStack, we need the library backing +``oslo.vmware``'s SOAP calls to be compatible with Python 3. We see +``suds-jurko`` as being unmaintained `upstream +`_, so we cannot rely on any changes +happening. Since we currently already see deprecation warnings generated by +nova's tests for Python 3.6, we need a fix before the release of Python 3.10 or +``oslo.vmware`` will stop working alltogether. + +Additionally, the vast number of VMs handled by a single compute-node with +``nova``'s VMware driver makes ``suds-jurko`` a performance bottleneck. This +can be overcome with switching to a library more optimized for parsing XML. + +Proposed change +=============== + +We propose to change the backing library of ``oslo.vmware`` to `zeep +`_. The library is + +* Still maintained +* Written for Python 2 and 3 +* Uses ``lxml`` for faster XML parsing + +With the interface of ``zeep`` being similar but not the same as ``suds``, we +have to introduce some compatibility functions. This is also necessary, because +some library-specific representation of objects, e.g. attribute access to +``ManagedObjectReference`` objects, leaked through to consuming projects. We +therefore propose to change the library and consuming projects in multiple +phases. + +.. rubric:: Phase 1 + +Add compatibility functions to ``oslo.vmware`` for value and type access of +``ManagedObjectReference`` and add additional functions/helpers for attribute +access to move all code using ``suds``-specificas into ``oslo.vmware``. + +.. rubric:: Phase 2 + +Introduce patches to ``cinder`` and ``nova`` for using the functions introduced +in phase 1. + +.. rubric:: Phase 3 + +Switch the code in ``oslo.vmware`` to use ``zeep`` instead of ``suds-jurko`` +while keeping the interface for consuming projects the same. The core of these +changes should be confined to ``oslo_vmware.service``. + +Alternatives +------------ + +There's another fork of ``suds-jurko`` called `suds-community +`_, which is still maintained, but +while using it may solve the Python compatibility problem it doesn't improve +performance. + +While there are other libraries around, see e.g. this list in the `Python wiki +`_, a quick glance at most of +them shows them as unmaintained, not supporting Python 3 or having an interface +that requires too many compatibility shims for keeping changes in consuming +projects minimal. + +Another alternative would be to get rid of ``oslo.vmware`` alltogether, which +is mainly hindered by nova and cinder still including drivers using this +library. + +Impact on Existing APIs +----------------------- + +Consuming code will be required to use the newly introduced helper-functions +for compatibility in attribute access. + +Security impact +--------------- + +None + +Performance Impact +------------------ + +With the XML parser of the library switching to the C-based ``lxml``, we expect +a performance increase. In our (very simple) tests, we achieved up to 50 % +reduction in request times and CPU load. + +Configuration Impact +-------------------- + +None + +Developer Impact +---------------- + +Consuming code will be required to use the newly introduced helper-functions +for compatibility in attribute access. + +Testing Impact +-------------- + +None + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + jkulik + +Milestones +---------- + +Target Milestone for completion: unclear + +Work Items +---------- + +* Implement helper functions in ``oslo.vmware`` for compatibility layer +* Patch ``nova``'s VMware driver to use helper functions +* Patch ``cinder``'s VMware driver to use helper functions +* Implement ``Service`` object using ``zeep`` client in ``oslo.vmware`` + +Documentation Impact +==================== + +None + +Dependencies +============ + +This adds ``zeep`` into OpenStack's requirements, while removing +``suds-jurko``. + +References +========== + +* Initial mailing list post: http://lists.openstack.org/pipermail/openstack-discuss/2020-March/013449.html +* Bug regarding ``suds`` packaging problems for debian: https://bugs.launchpad.net/oslo.vmware/+bug/1465016 + + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode +