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 neutron
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.
Overview¶
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 client’s
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
before the neutron
CLI is removed. Such users will maintain their OSC plugin
commands within their own project and will be responsible for deprecating and
removing their neutron
CLI extension.
Transition Steps¶
- Done: OSC adds OpenStack Python SDK as a dependency. See the following patch set: https://review.openstack.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.openstack.org/#/c/253348/
- Done: OSC removes its python-neutronclient dependency. See the following patch set: https://review.openstack.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.
- In Progress: 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:
- In Progress: OSC continues enhancing its networking support.
At this point and when applicable, enhancements to the
neutron
CLI must also be made to theopenstack
CLI and the OpenStack Python SDK. Enhancements to the networking support in the OpenStack Python SDK will be handled via bugs. 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. - Not Started: Deprecate the
neutron
CLI once the criteria below have been meet. Running the CLI after it has been deprecated will issue a warning messages such as the following:DeprecationWarning: The neutron CLI is deprecated in favor of python-openstackclient.
In addition, only security fixes will be made to the CLI after it has been deprecated.- The networking support provide by the
openstack
CLI is functionally equivalent to theneutron
CLI and it contains sufficient functional and unit test coverage. - Neutron Stadium
projects, Neutron documentation and DevStack
use
openstack
CLI instead ofneutron
CLI. - Most users of the neutron client’s command extensions have transitioned
to the OSC plugin system and use the
openstack
CLI instead of theneutron
CLI.
- The networking support provide by the
- Not Started: Remove the
neutron
CLI after two deprecation cycles.
Developer Guide¶
The neutron
CLI version 4.x, without extensions, supports over 200
commands while the openstack
CLI version 2.1.0 supports about 30
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
gap, a couple critical questions for developers during this transition are “Which
CLI do I change?” and “Where does my CLI belong?” The answer depends on the
state of a command and the state of the overall transition. Details are
outlined in the tables below. Early stages of the transition will require dual
maintenance. Eventually, dual maintenance will be reduced to critical bug fixes
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 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
file. openstack
networking commands outside python-openstackclient
are encouraged but not required to use the OpenStack Python SDK.
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.
Developer References¶
- See OSC neutron support etherpad
to determine if an
openstack
command is in progress. - See OSC command list
to determine if an
openstack
command exists. - See OSC command spec list
to determine if an
openstack
command spec exists. - See OSC plugin command list
to determine if an
openstack
plugin command exists. - See OSC command structure
to determine the current
openstack
command 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
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 OpenStack Python SDK bug: https://bugs.launchpad.net/python-openstacksdk/+filebug