Transition to OpenStack Client¶
This document details the transition roadmap for moving the neutron client’s
OpenStack Networking API support, both the Python library and the
command-line interface (CLI), to the
OpenStack Client (OSC)
and the OpenStack Python SDK.
This transition is being guided by the
Deprecate individual CLIs in favour of OSC
OpenStack spec. See the Neutron RFE,
OSC neutron support etherpad and
details below for the overall progress of this transition.
This transition will result in the neutron client’s
neutron CLI being
deprecated and then eventually removed. The
neutron CLI will be replaced
by OSC’s networking support available via the
openstack CLI. This is
similar to the deprecation and removal process for the
keystone CLI. The neutron client’s Python library won’t be deprecated.
It will be available along side the networking support provided by the
OpenStack Python SDK.
Users of the neutron client’s command extensions will need to transition to the
OSC plugin system
neutron CLI is removed. Such users will maintain their OSC plugin
commands within their own project and will be responsible for deprecating and
neutron CLI extension.
Done: OSC adds OpenStack Python SDK as a dependency. See the following patch set: https://review.opendev.org/#/c/138745/
Done: OSC switches its networking support for the network command object to use the OpenStack Python SDK instead of the neutron client’s Python library. See the following patch set: https://review.opendev.org/#/c/253348/
Done: OSC removes its python-neutronclient dependency. See the following patch set: https://review.opendev.org/#/c/255545/
In Progress: OpenStack Python SDK releases version 1.0 to guarantee backwards compatibility of its networking support and OSC updates its dependencies to include OpenStack Python SDK version 1.0 or later. See the following blueprint: https://blueprints.launchpad.net/python-openstackclient/+spec/network-command-sdk-support
Done: OSC switches its networking support for the ip floating, ip floating pool, ip fixed, security group, and security group rule command objects to use the OpenStack Python SDK instead of the nova client’s Python library when neutron is enabled. When nova network is enabled, then the nova client’s Python library will continue to be used. See the following OSC bugs:
Done Floating IP CRUD
Done Port CRUD
Done Security Group CRUD
Done OSC continues enhancing its networking support. At this point and when applicable, enhancements to the
neutronCLI must also be made to the
openstackCLI and possibly the OpenStack Python SDK. Users of the neutron client’s command extensions should start their transition to the OSC plugin system. See the developer guide section below for more information on this step.
Done Deprecate the
neutronCLI. Running the CLI after it has been deprecated will issue a warning message:
neutron CLI is deprecated and will be removed in the Z cycle. Use openstack CLI instead.In addition, no new features will be added to the CLI, though fixes to the CLI will be assessed on a case by case basis.
Done Remove the
neutronCLI after two deprecation cycles once the criteria below have been met.
The networking support provide by the
openstackCLI is functionally equivalent to the
neutronCLI and it contains sufficient functional and unit test coverage.
Neutron Stadium projects, Neutron documentation and DevStack use
openstackCLI instead of
Most users of the neutron client’s command extensions have transitioned to the OSC plugin system and use the
openstackCLI instead of the
neutron CLI tool is now removed and all new CLI changes should be done
OpenStackClient (OSC) and, if needed, also in the
Where does my CLI belong?
If you are developing an API in any of the neutron repos the client-side support must be generally located in either the openstackclient or neutronclient repos. Whether the actual code goes into one or the other repo it depends on the nature of the feature, its maturity level, and/or the depth of feedback required during the development.
The table below provides an idea of what goes where. Generally speaking, we consider Core anything that is L2 and L3 related or that it has been located in the neutron repo for quite sometime, e.g. QoS or Metering, or that it is available in each neutron deployment irrespective of its configuration (e.g. auto-allocated-topology). Any client feature that falls into this categorization will need to be contributed in OSC. Any other that does not, will need to go into neutronclient, assuming that its server-side is located in a neutron controlled repo. This is a general guideline, when in doubt, please reach out to a member of the neutron core team for clarifications.
OpenStack Project for
Extension (i.e. neutron stadium)
Applicable project owning networking resource
When a repo stops being under neutron governance, its client-side counterpart will have to go through deprecation. Bear in mind that for grandfathered extensions like FWaaS v1, VPNaaS, and LBaaS v1, this is not required as the neutronclient is already deprecated on its own.
Which Python library do I change?
OpenStack Project for
Python Library to Change
Applicable project owning network resource
Important: The actual name of the command object and/or action in OSC may differ from those used by neutron in order to follow the OSC command structure and to avoid name conflicts. The network prefix must be used to avoid name conflicts if the command object name is highly likely to have an ambiguous meaning. Developers should get new command objects and actions approved by the OSC team before proceeding with the implementation.
The “Core” group includes network resources that provide core
features (e.g. network, subnet, port, etc.) and not advanced features in the
neutron project (e.g. trunk, etc.) or advanced services in separate projects
(FWaaS, LBaaS, VPNaaS, dynamic routing, etc.).
The “Other” group applies projects other than the core
Contact the neutron PTL or core team with questions on network resource classification.
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
When adding an
openstack networking command to python-openstackclient,
you can optionally propose an
OSC command spec
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 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 which command to change.
See OSC neutron support etherpad to determine if an
openstackcommand is in progress.
See OSC command list to determine if an
See OSC command spec list to determine if an
openstackcommand spec exists.
See OSC plugin command list to determine if an
openstackplugin command exists.
See OSC command structure to determine the current
openstackcommand objects, plugin objects and actions.
See OSC human interface guide for guidance on creating new OSC command interfaces.
See OSC plugin for information on the OSC plugin system to be used for
Create an OSC blueprint: https://blueprints.launchpad.net/python-openstackclient/
Report an OSC bug: https://bugs.launchpad.net/python-openstackclient/+filebug
Report an OpenStack Python SDK bug: https://bugs.launchpad.net/python-openstacksdk/+filebug