openstack/python-neutronclient
Code Issues Proposed changes

Merge "Devref Update: Transition to OpenStack Client"

Browse Source
This commit is contained in:
Jenkins
2016-03-02 17:32:21 +00:00
committed by Gerrit Code Review
parent e9560866f7 585a4ffbfa
commit e2444d4f53
1 changed files with 104 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
doc/source/devref/transition_to_osc.rst
View File

@@ -26,13 +26,13 @@ Transition to OpenStack Client
This document details the transition roadmap for moving the neutron client's This document details the transition roadmap for moving the neutron client's
OpenStack Networking API support, both the Python library and the ``neutron`` OpenStack Networking API support, both the Python library and the ``neutron``
command-line interface (CLI), to the command-line interface (CLI), to the
`OpenStack client (OSC) <https://github.com/openstack/python-openstackclient>`_ `OpenStack Client (OSC) <https://github.com/openstack/python-openstackclient>`_
and the `OpenStack Python SDK <https://github.com/openstack/python-openstacksdk>`_. and the `OpenStack Python SDK <https://github.com/openstack/python-openstacksdk>`_.
This transition is being guided by the This transition is being guided by the
`Deprecate individual CLIs in favour of OSC <https://review.openstack.org/#/c/243348/>`_ `Deprecate individual CLIs in favour of OSC <https://review.openstack.org/#/c/243348/>`_
OpenStack spec. See the `Neutron RFE <https://bugs.launchpad.net/neutron/+bug/1521291>`_ and OpenStack spec. See the `Neutron RFE <https://bugs.launchpad.net/neutron/+bug/1521291>`_,
`OSC neutron-client blueprint <https://blueprints.launchpad.net/python-openstackclient/+spec/neutron-client>`_ `OSC neutron support etherpad <https://etherpad.openstack.org/p/osc-neutron-support>`_ and
for the overall progress of this transition. details below for the overall progress of this transition.
Overview Overview
-------- --------
@@ -42,17 +42,15 @@ deprecated and then eventually removed. The ``neutron`` CLI will be replaced
by OSC's networking support available via the ``openstack`` CLI. This is by OSC's networking support available via the ``openstack`` CLI. This is
similar to the deprecation and removal process for the similar to the deprecation and removal process for the
`keystone client's <https://github.com/openstack/python-keystoneclient>`_ `keystone client's <https://github.com/openstack/python-keystoneclient>`_
``keystone`` CLI. ``keystone`` CLI. The neutron client's Python library won't be deprecated.
It will be available along side the networking support provided by the
The neutron client's Python library won't be deprecated. It will be available OpenStack Python SDK.
along side the networking support provided by the OpenStack Python SDK. However,
the OpenStack Python SDK will be used to implement OSC's networking support.
Users of the neutron client's command extensions will need to transition to the Users of the neutron client's command extensions will need to transition to the
`OSC plugin system <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_ `OSC plugin system <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_
before the ``neutron`` CLI is removed. Such users will maintain their OSC plugin before the ``neutron`` CLI is removed. Such users will maintain their OSC plugin
within their own project and will be responsible for deprecating and removing commands within their own project and will be responsible for deprecating and
their ``neutron`` CLI extension. removing their ``neutron`` CLI extension.
Transition Steps Transition Steps
---------------- ----------------
@@ -92,13 +90,12 @@ Transition Steps
* `Security Group Rule CRUD <https://bugs.launchpad.net/python-openstackclient/+bug/1519512>`_ * `Security Group Rule CRUD <https://bugs.launchpad.net/python-openstackclient/+bug/1519512>`_
6. **In Progress:** OSC enhances its networking support under the 6. **In Progress:** OSC continues enhancing its networking support.
`neutron-client <https://blueprints.launchpad.net/python-openstackclient/+spec/neutron-client>`_ At this point and when applicable, enhancements to the ``neutron``
OSC spec. At this point and when applicable, enhancements to the ``neutron``
CLI must also be made to the ``openstack`` CLI and the OpenStack Python SDK. CLI must also be made to the ``openstack`` CLI and the OpenStack Python SDK.
Enhancements to the networking support in the OpenStack Python SDK will be Enhancements to the networking support in the OpenStack Python SDK will be
handled via bugs. Neutron stadium users of the neutron client's command handled via bugs. Users of the neutron client's command extensions should
extensions should start their transition to the OSC plugin system. start their transition to the OSC plugin system.
See the developer guide section below for more information on this step. See the developer guide section below for more information on this step.
7. **Not Started:** Deprecate the ``neutron`` CLI once the criteria below have 7. **Not Started:** Deprecate the ``neutron`` CLI once the criteria below have
@@ -112,64 +109,116 @@ Transition Steps
equivalent to the ``neutron`` CLI and it contains sufficient functional equivalent to the ``neutron`` CLI and it contains sufficient functional
and unit test coverage. and unit test coverage.
* Neutron core and advanced services projects, Neutron documentation and * `Neutron Stadium <http://docs.openstack.org/developer/neutron/stadium/sub_projects.html>`_
`DevStack <http://docs.openstack.org/developer/devstack/>`_ use ``openstack`` projects, Neutron documentation and `DevStack <http://docs.openstack.org/developer/devstack/>`_
CLI instead of ``neutron`` CLI. use ``openstack`` CLI instead of ``neutron`` CLI.
* Most neutron stadium users of the neutron client's command extensions have * Most users of the neutron client's command extensions have transitioned
transitioned to the OSC plugin system and use the ``openstack`` CLI instead to the OSC plugin system and use the ``openstack`` CLI instead of the
of the ``neutron`` CLI. ``neutron`` CLI.
8. **Not Started:** Remove the ``neutron`` CLI after two deprecation cycles. 8. **Not Started:** Remove the ``neutron`` CLI after two deprecation cycles.
Developer Guide Developer Guide
--------------- ---------------
The ``neutron`` CLI version 3.1.1, without extensions, supports over 200 The ``neutron`` CLI version 4.x, without extensions, supports over 200
commands while the ``openstack`` CLI version 2.0.1 supports about 20 commands while the ``openstack`` CLI version 2.1.0 supports about 30
networking commands. Of the 20 commands, most do not have all of the options networking commands. Of the 30 commands, many do not have all of the options
or arguments of their ``neutron`` CLI equivalent. With this large functional or arguments of their ``neutron`` CLI equivalent. With this large functional
gap, one critical question for developers during this transition is "Which gap, a couple critical questions for developers during this transition are "Which
CLI do I change?" The answer depends on the state of a command and the CLI do I change?" and "Where does my CLI belong?" The answer depends on the
state of the overall transition. Details are outlined in the table state of a command and the state of the overall transition. Details are
below. Early stages of the transition will require dual maintenance. outlined in the tables below. Early stages of the transition will require dual
Eventually, dual maintenance will be reduced to critical bug fixes only maintenance. Eventually, dual maintenance will be reduced to critical bug fixes
with feature requests only being made to the ``openstack`` CLI. only with feature requests only being made to the ``openstack`` CLI.
+----------------------+------------------------+----------------------------------------------+ **Which CLI do I change?**
| neutron Command | openstack Command | CLI to Change |
+======================+========================+==============================================+
| Exists | Doesn't Exist | neutron |
+----------------------+------------------------+----------------------------------------------+
| Exists | In Progress | neutron and update related OSC bug |
+----------------------+------------------------+----------------------------------------------+
| Exists | Exists | neutron and openstack |
+----------------------+------------------------+----------------------------------------------+
| Doesn't Exist | Doesn't Exist | neutron and openstack |
+----------------------+------------------------+----------------------------------------------+
| Doesn't Exist | Exists | openstack |
+----------------------+------------------------+----------------------------------------------+
When adding or updating an ``openstack`` networking command, changes may +----------------------+------------------------+-------------------------------------------------+
first be required to the OpenStack Python SDK to support the underlying | ``neutron`` Command | ``openstack`` Command | CLI to Change |
networking resource object, properties and/or actions. Once the OpenStack +======================+========================+=================================================+
Python SDK changes are merged, the related OSC changes can be merged. | Exists | Doesn't Exist | ``neutron`` |
The OSC changes may require an update to the OSC openstacksdk version in the +----------------------+------------------------+-------------------------------------------------+
| Exists | In Progress | ``neutron`` and ``openstack`` |
| | | (update related blueprint or bug) |
+----------------------+------------------------+-------------------------------------------------+
| Exists | Exists | ``openstack`` |
| | | (assumes command parity resulting in |
| | | ``neutron`` being deprecated) |
+----------------------+------------------------+-------------------------------------------------+
| Doesn't Exist | Doesn't Exist | ``openstack`` |
+----------------------+------------------------+-------------------------------------------------+
**Where does my CLI belong?**
+---------------------------+-------------------+-------------------------------------------------+
| Networking Commands | OSC Plugin | OpenStack Project for ``openstack`` Commands |
+===========================+===================+=================================================+
| Core (Stable) | No | python-openstackclient |
+---------------------------+-------------------+-------------------------------------------------+
| Core (New/Experimental) | Yes | python-neutronclient |
| | | (with possible move to python-openstackclient) |
+---------------------------+-------------------+-------------------------------------------------+
| LBaaS v2 | Yes | neutron-lbaas |
+---------------------------+-------------------+-------------------------------------------------+
| VPNaaS v2 | Yes | neutron-vpnaas |
+---------------------------+-------------------+-------------------------------------------------+
| FWaaS v2 | Yes | neutron-fwaas |
+---------------------------+-------------------+-------------------------------------------------+
| LBaaS v1 | N/A | None (deprecated) |
+---------------------------+-------------------+-------------------------------------------------+
| FWaaS v1 | N/A | None (deprecated) |
+---------------------------+-------------------+-------------------------------------------------+
| Other | Yes | Applicable project owning networking resource |
+---------------------------+-------------------+-------------------------------------------------+
The following network resources are part of the "Core (Stable)" group:
- availability zone
- extension
- floating ip
- network
- port
- quota
- rbac
- router
- security group
- security group rule
- subnet
- subnet pool
When adding or updating an ``openstack`` networking command to
python-openstackclient, changes may first be required to the
OpenStack Python SDK to support the underlying networking resource object,
properties and/or actions. Once the OpenStack Python SDK changes are merged,
the related OSC changes can be merged. The OSC changes may require an update
to the OSC openstacksdk version in the
`requirements.txt <https://github.com/openstack/python-openstackclient/blob/master/requirements.txt>`_ `requirements.txt <https://github.com/openstack/python-openstackclient/blob/master/requirements.txt>`_
file. file. ``openstack`` networking commands outside python-openstackclient
are encouraged but not required to use the OpenStack Python SDK.
Neutron stadium users of the neutron client's command extensions must adopt the When adding an ``openstack`` networking command to python-openstackclient,
you can optionally propose an
`OSC command spec <https://github.com/openstack/python-openstackclient/blob/master/doc/source/specs/commands.rst>`_
which documents the new command interface before proceeding with the implementation.
Users of the neutron client's command extensions must adopt the
`OSC plugin system <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_ `OSC plugin system <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_
for this transition. Such users will maintain their OSC plugin within their for this transition. Such users will maintain their OSC plugin within their
own project and should follow the guidance in the table above to determine own project and should follow the guidance in the table above to determine
which CLI to change. which command to change.
Developer References Developer References
-------------------- --------------------
* See `OSC neutron-client blueprint <https://blueprints.launchpad.net/python-openstackclient/+spec/neutron-client>`_ * See `OSC neutron support etherpad <https://etherpad.openstack.org/p/osc-neutron-support>`_
to determine if an ``openstack`` command is in progress. See the ``Related bugs`` list. to determine if an ``openstack`` command is in progress.
* See `OSC command list <http://docs.openstack.org/developer/python-openstackclient/command-list.html>`_ * See `OSC command list <http://docs.openstack.org/developer/python-openstackclient/command-list.html>`_
to determine if an ``openstack`` command exists. to determine if an ``openstack`` command exists.
* See `OSC command spec list <https://github.com/openstack/python-openstackclient/tree/master/doc/source/specs/command-objects>`_
to determine if an ``openstack`` command spec exists.
* See `OSC plugin command list <http://docs.openstack.org/developer/python-openstackclient/plugin-commands.html>`_ * See `OSC plugin command list <http://docs.openstack.org/developer/python-openstackclient/plugin-commands.html>`_
to determine if an ``openstack`` plugin command exists. to determine if an ``openstack`` plugin command exists.
* See `OSC command structure <http://docs.openstack.org/developer/python-openstackclient/commands.html>`_ * See `OSC command structure <http://docs.openstack.org/developer/python-openstackclient/commands.html>`_
@@ -178,5 +227,6 @@ Developer References
for guidance on creating new OSC command interfaces. for guidance on creating new OSC command interfaces.
* See `OSC plugin <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_ * See `OSC plugin <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_
for information on the OSC plugin system to be used for ``neutron`` CLI extensions. for information on the OSC plugin system to be used for ``neutron`` CLI extensions.
* Create an OSC blueprint: https://blueprints.launchpad.net/python-openstackclient/
* Report an OSC bug: https://bugs.launchpad.net/python-openstackclient/+filebug * Report an OSC bug: https://bugs.launchpad.net/python-openstackclient/+filebug
* Report an OpenStack Python SDK bug: https://bugs.launchpad.net/python-openstacksdk/+filebug * Report an OpenStack Python SDK bug: https://bugs.launchpad.net/python-openstacksdk/+filebug