Debian Codegraph @

doc/source/contributor/transition_to_osc.rst

raw
1 ..
2 Licensed under the Apache License, Version 2.0 (the "License"); you may
3 not use this file except in compliance with the License. You may obtain
4 a copy of the License at
5
6 http://www.apache.org/licenses/LICENSE-2.0
7
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11 License for the specific language governing permissions and limitations
12 under the License.
13
14
15 Convention for heading levels in Neutron devref:
16 ======= Heading 0 (reserved for the title in a document)
17 ------- Heading 1
18 ~~~~~~~ Heading 2
19 +++++++ Heading 3
20 ''''''' Heading 4
21 (Avoid deeper levels because they do not render well.)
22
23 Transition to OpenStack Client
24 ==============================
25
26 This document details the transition roadmap for moving the neutron client's
27 OpenStack Networking API support, both the Python library and the ``neutron``
28 command-line interface (CLI), to the
29 `OpenStack Client (OSC) <https://github.com/openstack/python-openstackclient>`_
30 and the `OpenStack Python SDK <https://github.com/openstack/openstacksdk>`_.
31 This transition is being guided by the
32 `Deprecate individual CLIs in favour of OSC <https://review.opendev.org/#/c/243348/>`_
33 OpenStack spec. See the `Neutron RFE <https://bugs.launchpad.net/neutron/+bug/1521291>`_,
34 `OSC neutron support etherpad <https://etherpad.openstack.org/p/osc-neutron-support>`_ and
35 details below for the overall progress of this transition.
36
37 Overview
38 --------
39
40 This transition will result in the neutron client's ``neutron`` CLI being
41 deprecated and then eventually removed. The ``neutron`` CLI will be replaced
42 by OSC's networking support available via the ``openstack`` CLI. This is
43 similar to the deprecation and removal process for the
44 `keystone client's <https://github.com/openstack/python-keystoneclient>`_
45 ``keystone`` CLI. The neutron client's Python library won't be deprecated.
46 It will be available along side the networking support provided by the
47 OpenStack Python SDK.
48
49 Users of the neutron client's command extensions will need to transition to the
50 `OSC plugin system <https://docs.openstack.org/python-openstackclient/latest/contributor/plugins.html>`_
51 before the ``neutron`` CLI is removed. Such users will maintain their OSC plugin
52 commands within their own project and will be responsible for deprecating and
53 removing their ``neutron`` CLI extension.
54
55 Transition Steps
56 ----------------
57
58 1. **Done:** OSC adds OpenStack Python SDK as a dependency. See the following
59 patch set: https://review.opendev.org/#/c/138745/
60
61 2. **Done:** OSC switches its networking support for the
62 `network <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/network.html>`_
63 command object to use the OpenStack Python SDK instead of the neutron
64 client's Python library. See the following patch set:
65 https://review.opendev.org/#/c/253348/
66
67 3. **Done:** OSC removes its python-neutronclient dependency.
68 See the following patch set: https://review.opendev.org/#/c/255545/
69
70 4. **In Progress:** OpenStack Python SDK releases version 1.0 to guarantee
71 backwards compatibility of its networking support and OSC updates
72 its dependencies to include OpenStack Python SDK version 1.0 or later.
73 See the following blueprint: https://blueprints.launchpad.net/python-openstackclient/+spec/network-command-sdk-support
74
75 5. **Done:** OSC switches its networking support for the
76 `ip floating <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/ip-floating.html>`_,
77 `ip floating pool <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/ip-floating-pool.html>`_,
78 `ip fixed <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/ip-fixed.html>`_,
79 `security group <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/security-group.html>`_, and
80 `security group rule <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/security-group-rule.html>`_
81 command objects to use the OpenStack Python SDK instead of the nova
82 client's Python library when neutron is enabled. When nova network
83 is enabled, then the nova client's Python library will continue to
84 be used. See the following OSC bugs:
85
86 * **Done** `Floating IP CRUD <https://bugs.launchpad.net/python-openstackclient/+bug/1519502>`_
87
88 * **Done** `Port CRUD <https://bugs.launchpad.net/python-openstackclient/+bug/1519909>`_
89
90 * **Done** `Security Group CRUD <https://bugs.launchpad.net/python-openstackclient/+bug/1519511>`_
91
92 * **Done** `Security Group Rule CRUD <https://bugs.launchpad.net/python-openstackclient/+bug/1519512>`_
93
94 6. **Done** OSC continues enhancing its networking support.
95 At this point and when applicable, enhancements to the ``neutron``
96 CLI must also be made to the ``openstack`` CLI and possibly the
97 OpenStack Python SDK. Users of the neutron client's command extensions
98 should start their transition to the OSC plugin system. See the
99 developer guide section below for more information on this step.
100
101 7. **Done** Deprecate the ``neutron`` CLI. Running the CLI after
102 it has been `deprecated <https://review.opendev.org/#/c/393903/>`_
103 will issue a warning message:
104 ``neutron CLI is deprecated and will be removed in the Z cycle. Use openstack CLI instead.``
105 In addition, no new features will be added to the CLI, though fixes to
106 the CLI will be assessed on a case by case basis.
107
108 8. **Done** Remove the ``neutron`` CLI after two deprecation cycles
109 once the criteria below have been met.
110
111 * The networking support provide by the ``openstack`` CLI is functionally
112 equivalent to the ``neutron`` CLI and it contains sufficient functional
113 and unit test coverage.
114
115 * `Neutron Stadium <https://docs.openstack.org/neutron/latest/contributor/stadium/>`_
116 projects, Neutron documentation and `DevStack <https://docs.openstack.org/devstack/latest/>`_
117 use ``openstack`` CLI instead of ``neutron`` CLI.
118
119 * Most users of the neutron client's command extensions have transitioned
120 to the OSC plugin system and use the ``openstack`` CLI instead of the
121 ``neutron`` CLI.
122
123 Developer Guide
124 ---------------
125 The ``neutron`` CLI tool is now removed and all new CLI changes should be done
126 in the ``OpenStackClient (OSC)`` and, if needed, also in the ``OpenStack SDK``.
127
128 **Where does my CLI belong?**
129
130 If you are developing an API in any of the `neutron repos <https://governance.openstack.org/tc/reference/projects/neutron.html>`_
131 the client-side support must be generally located in either the openstackclient or neutronclient
132 repos. Whether the actual code goes into one or the other repo it depends on the nature of the
133 feature, its maturity level, and/or the depth of feedback required during the development.
134
135 The table below provides an idea of what goes where. Generally speaking, we consider Core anything
136 that is L2 and L3 related or that it has been located in the neutron repo for quite sometime, e.g.
137 QoS or Metering, or that it is available in each neutron deployment irrespective of its configuration
138 (e.g. auto-allocated-topology). Any client feature that falls into this categorization will need to
139 be contributed in OSC. Any other that does not, will need to go into neutronclient, assuming that
140 its server-side is located in a neutron controlled repo. This is a general guideline, when in doubt,
141 please reach out to a member of the neutron core team for clarifications.
142
143 +---------------------------+-------------------+-------------------------------------------------+
144 | Networking Commands | OSC Plugin | OpenStack Project for ``openstack`` Commands |
145 +===========================+===================+=================================================+
146 | Core | No | python-openstackclient |
147 +---------------------------+-------------------+-------------------------------------------------+
148 | Extension | Yes | python-neutronclient |
149 | (i.e. neutron stadium) | | (``neutronclient/osc/v2/<extension>``) |
150 +---------------------------+-------------------+-------------------------------------------------+
151 | Other | Yes | Applicable project owning networking resource |
152 +---------------------------+-------------------+-------------------------------------------------+
153
154 When a repo stops being under neutron governance, its client-side counterpart will have to go through
155 deprecation. Bear in mind that for grandfathered extensions like FWaaS v1, VPNaaS, and LBaaS v1, this
156 is not required as the neutronclient is already deprecated on its own.
157
158 **Which Python library do I change?**
159
160 +-------------------------------------------------+-----------------------------------------------+
161 | OpenStack Project for ``openstack`` Commands | Python Library to Change |
162 +=================================================+===============================================+
163 | python-openstackclient | openstacksdk |
164 +-------------------------------------------------+-----------------------------------------------+
165 | Other | Applicable project owning network resource |
166 +-------------------------------------------------+-----------------------------------------------+
167
168
169 **Important:** The actual name of the command object and/or action in OSC may differ
170 from those used by neutron in order to follow the OSC command structure and to avoid
171 name conflicts. The `network` prefix must be used to avoid name conflicts if the
172 command object name is highly likely to have an ambiguous meaning. Developers should
173 get new command objects and actions approved by the OSC team before proceeding with the
174 implementation.
175
176 The "Core" group includes network resources that provide core ``neutron`` project
177 features (e.g. network, subnet, port, etc.) and not advanced features in the
178 ``neutron`` project (e.g. trunk, etc.) or advanced services in separate projects
179 (FWaaS, LBaaS, VPNaaS, dynamic routing, etc.).
180 The "Other" group applies projects other than the core ``neutron`` project.
181 Contact the neutron PTL or core team with questions on network resource classification.
182
183 When adding or updating an ``openstack`` networking command to
184 python-openstackclient, changes may first be required to the
185 OpenStack Python SDK to support the underlying networking resource object,
186 properties and/or actions. Once the OpenStack Python SDK changes are merged,
187 the related OSC changes can be merged. The OSC changes may require an update
188 to the OSC openstacksdk version in the
189 `requirements.txt <https://github.com/openstack/python-openstackclient/blob/master/requirements.txt>`_
190 file.
191
192 When adding an ``openstack`` networking command to python-openstackclient,
193 you can optionally propose an
194 `OSC command spec <https://github.com/openstack/python-openstackclient/blob/master/doc/source/contributor/specs/commands.rst>`_
195 which documents the new command interface before proceeding with the implementation.
196
197 Users of the neutron client's command extensions must adopt the
198 `OSC plugin <https://github.com/openstack/python-openstackclient/blob/master/doc/source/contributor/plugins.rst>`_
199 system for this transition. Such users will maintain their OSC plugin within their
200 own project and should follow the guidance in the table above to determine
201 which command to change.
202
203 Developer References
204 --------------------
205
206 * See `OSC neutron support etherpad <https://etherpad.openstack.org/p/osc-neutron-support>`_
207 to determine if an ``openstack`` command is in progress.
208 * See `OSC command list <https://github.com/openstack/python-openstackclient/tree/master/doc/source/cli/command-objects>`_
209 to determine if an ``openstack`` command exists.
210 * See `OSC command spec list <https://github.com/openstack/python-openstackclient/tree/master/doc/source/contributor/specs/command-objects>`_
211 to determine if an ``openstack`` command spec exists.
212 * See `OSC plugin command list <https://docs.openstack.org/python-openstackclient/latest/cli/plugin-commands.html>`_
213 to determine if an ``openstack`` plugin command exists.
214 * See `OSC command structure <https://github.com/openstack/python-openstackclient/blob/master/doc/source/cli/commands.rst>`_
215 to determine the current ``openstack`` command objects, plugin objects and actions.
216 * See `OSC human interface guide <https://github.com/openstack/python-openstackclient/blob/master/doc/source/contributor/humaninterfaceguide.rst>`_
217 for guidance on creating new OSC command interfaces.
218 * See `OSC plugin <https://github.com/openstack/python-openstackclient/blob/master/doc/source/contributor/plugins.rst>`_
219 for information on the OSC plugin system to be used for ``neutron`` CLI extensions.
220 * Create an OSC blueprint: https://blueprints.launchpad.net/python-openstackclient/
221 * Report an OSC bug: https://bugs.launchpad.net/python-openstackclient/+filebug
222 * Report an OpenStack Python SDK bug: https://bugs.launchpad.net/python-openstacksdk/+filebug