networking guide does not explain what OVS version 2.1 is needed for

[Mike Spreitzer]

http://docs.openstack.org/networking-guide/scenario_legacy_ovs.html includes a warning that

"Proper operation of this scenario requires Open vSwitch 2.1 or newer"

--- but does not explain what part of the scenario requires that.

[Mike Spreitzer (mike-spreitzer)]

(I would have opened this bug against the relevant documentation project --- if only that were documented!)

[Matt Kassawara (ionosphere80)]

I think we decided on Open vSwitch 2.1 as the minimum version for the following reasons:

1) It includes several performance increases and bug fixes that provide the best experience for our primary audience - relatively new users of OpenStack.

2) It includes functionality that allows our audience to incrementally investigate and implement more complex scenarios such as DVR and L3 HA without upgrading OVS.

[Matt Kassawara (ionosphere80)]

Also, did you see the little icon of a bug in the upper right-hand corner of the page containing this issue? If not, we have a build/publication problem.

[Mike Spreitzer (mike-spreitzer)]

No, I did not notice that icon --- but I see it now. Thanks!

[Mike Spreitzer (mike-spreitzer)]

Thanks Matt for the info here. It needs to get into the networking guide. And somebody should tell the DevStack people about this, following the published instructions for DevStack on Ubuntu gets version 2.0.2 of OVS and it did not function properly for me.

[Matt Kassawara (ionosphere80)]

Right, stock Ubuntu 14.04 images include OVS 2.0.2. Most people who install OpenStack the first few times use packages from either the cloud archive (Ubuntu) or RDO (RHEL/CentOS) repositories that include newer versions of OVS rather than DevStack. Excluding the step-by-step installation guide, the documentation tries to avoid distribution-specific content because many production installations do not use distribution packages and they sometimes contain quirks not relevant to upstream OpenStack. I think we should add a note to the networking guide explaining why the audience should avoid OVS versions prior to 2.1, but not explaining how to obtain newer releases. However, we should first ask Russell Bryant to validate this position and perhaps suggest content for the note.

[Mike Spreitzer (mike-spreitzer)]

Remember there are two categories of documentation to consider. There is the documentation for operators who deploy OpenStack for production use, and there is the DevStack documentation for OpenStack developers. I agree we do not want to get into the business of maintaining excessively detailed information. But both categories of documentation should include sufficient clues.

[Mike Spreitzer (mike-spreitzer)]

Right now http://docs.openstack.org/developer/devstack/guides/neutron.html gives a developer using DevStack no clue that he has to take extra steps to get a sufficient version of OVS.

Right now the note in http://docs.openstack.org/networking-guide/scenario_legacy_ovs.html is worded in a way that suggests that versions less than 2.1 will work in other scenarios and possibly for subsets of the functionality involved on that page. If the actual intent is that 2.1 is required, period, then the wording should be stronger.

[Matt Kassawara (ionosphere80)]

The documentation team maintains documentation for administrators/operators/users who use (or plan to use) production deployments of OpenStack instead of DevStack. Developers should maintain documentation for developers including how to deploy DevStack in the most practical way for each project. For example, installing a recent version of OVS for neutron development. I wish the documentation team could involve itself in developer documentation, but it barely keeps pace with administrator/operator/user documentation. Ideally, each project should dedicate a couple of people to maintain developer documentation and assist the documentation team as necessary to produce usable, accurate documentation for administrators/operators/users looking to deploy the project in production.

A note about DevStack... I think it still defaults to nova-net and considers neutron an option specifically for neutron developers rather than a core component, hence why the documentation for it doesn't receive much love. The neutron gate jobs that use DevStack may perform additional actions to optimize testing of neutron patches, but documentation seems scarce and usually requires sifting through code.

[Mike Spreitzer (mike-spreitzer)]

Yes, this bug can focus on the doc issue for operators; I have opened a separate bug (https://bugs.launchpad.net/devstack/+bug/1529446) for the DevStack issue.

[Mike Spreitzer (mike-spreitzer)]

Please remember also that merely citing an OVS version number is not sufficient to identify the needed OVS functionality. As explained at https://github.com/openvswitch/ovs/blob/master/FAQ.md#q-are-all-features-available-with-all-datapaths , a given version of OVS may have more or less functionality depending on which "datapath" is used.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/263808

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/263808
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=2f93db879e04de91885cc1b5986251bc31e1862a
Submitter: Jenkins
Branch: master

commit 2f93db879e04de91885cc1b5986251bc31e1862a
Author: Matthew Kassawara <email address hidden>
Date: Tue Jan 5 09:56:36 2016 -0700

    [network] Improve note about minimum OVS version

    Provide more details in note regarding minimum version
    of Open vSwitch necessary for the best experience with
    scenarios that use it.

    Change-Id: Ifa3c0b511c8e216f13180cbb107e377d22536312
    Closes-Bug: #1529444
    backport: liberty
    backport: kilo

[Mike Spreitzer (mike-spreitzer)]

Thanks, Matt, for doing something about this. However, the docs and DevStack are now even more opposed to each other. The main Neutron doc recommends the latest LTS version of OVS, and following http://docs.openstack.org/developer/devstack/guides/neutron.html gets you OVS 2.0.2 (as noted in bug 1529446). When something goes wrong in OVS, I am left uncertain whether I am using a reasonable version.

[Mike Spreitzer (mike-spreitzer)]

I am also left uncertain whether my problem is that I made the wrong choice of datapath.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/liberty
Review: https://review.openstack.org/267728

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/267728
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=23bff644f36168212b757ec6f9ed3f7919579d53
Submitter: Jenkins
Branch: stable/liberty

commit 23bff644f36168212b757ec6f9ed3f7919579d53
Author: Matthew Kassawara <email address hidden>
Date: Tue Jan 5 09:56:36 2016 -0700

    [network] Improve note about minimum OVS version

    Provide more details in note regarding minimum version
    of Open vSwitch necessary for the best experience with
    scenarios that use it.

    Closes-Bug: #1529444
    backport: liberty
    backport: kilo
    (cherry picked from commit 2f93db879e04de91885cc1b5986251bc31e1862a)

    Conflicts:
     doc/networking-guide/source/scenario_dvr_ovs.rst
     doc/networking-guide/source/scenario_l3ha_ovs.rst
     doc/networking-guide/source/scenario_legacy_ovs.rst

    Change-Id: Ifa3c0b511c8e216f13180cbb107e377d22536312

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/kilo
Review: https://review.openstack.org/270570

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/270570
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=37ed93d1ab7e83e41bb04c46aa58985cc58df81e
Submitter: Jenkins
Branch: stable/kilo

commit 37ed93d1ab7e83e41bb04c46aa58985cc58df81e
Author: Matthew Kassawara <email address hidden>
Date: Tue Jan 5 09:56:36 2016 -0700

    [network] Improve note about minimum OVS version

    Provide more details in note regarding minimum version
    of Open vSwitch necessary for the best experience with
    scenarios that use it.

    Closes-Bug: #1529444
    backport: liberty
    backport: kilo
    (cherry picked from commit 2f93db879e04de91885cc1b5986251bc31e1862a)

    Change-Id: Ifa3c0b511c8e216f13180cbb107e377d22536312
    (cherry picked from commit 23bff644f36168212b757ec6f9ed3f7919579d53)

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/openstack-manuals 15.0.0 release.