diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/cli/index.rst | 14 | ||||
| -rw-r--r-- | doc/source/cli/neutron-reference.rst | 48 | ||||
| -rw-r--r-- | doc/source/cli/neutron.rst | 412 | ||||
| -rw-r--r-- | doc/source/contributor/cli_option_guideline.rst | 263 | ||||
| -rw-r--r-- | doc/source/contributor/client_command_extensions.rst | 97 | ||||
| -rw-r--r-- | doc/source/contributor/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/contributor/transition_to_osc.rst | 32 | ||||
| -rw-r--r-- | doc/source/index.rst | 10 |
8 files changed, 9 insertions, 869 deletions
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index 0a7d54d..4b1f472 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -24,10 +24,9 @@ Using CLI ========= -There are two CLIs which support the Networking API: -`OpenStackClient (OSC) +There is `OpenStackClient (OSC) <https://docs.openstack.org/python-openstackclient/latest/>`__ -and :doc:`neutron CLI <neutron>` (deprecated). +which support the Networking API OpenStackClient --------------- @@ -49,15 +48,8 @@ neutron CLI .. warning:: - neutron CLI is now deprecated and will be removed in the future. - Use openstack CLI instead. See `openstack CLI command list + neutron CLI is removed. Use openstack CLI instead. See `openstack CLI command list <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__ and :doc:`its extensions for advanced networking services <osc_plugins>`. The command mapping from neutron CLI to openstack CLI is available `here <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>`__. - -.. toctree:: - :maxdepth: 2 - - neutron CLI guide <neutron> - neutron CLI reference <neutron-reference> diff --git a/doc/source/cli/neutron-reference.rst b/doc/source/cli/neutron-reference.rst deleted file mode 100644 index d6640ea..0000000 --- a/doc/source/cli/neutron-reference.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - - Convention for heading levels in Neutron devref: - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - (Avoid deeper levels because they do not render well.) - -===================== -neutron CLI reference -===================== - -.. warning:: - - neutron CLI is now deprecated and will be removed in the future. - Use openstack CLI instead. See `openstack CLI command list - <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__ - and :doc:`its extensions for advanced networking services <osc_plugins>`. - The command mapping from neutron CLI to openstack CLI is available - `here <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>`__. - -neutron usage -------------- - -.. autoprogram-cliff:: neutronclient.shell.NeutronShell - :application: neutron - :arguments: 2.0 - -neutron API v2.0 commands -------------------------- - -.. autoprogram-cliff:: neutron.cli.v2 - :application: neutron - diff --git a/doc/source/cli/neutron.rst b/doc/source/cli/neutron.rst deleted file mode 100644 index 7ca6527..0000000 --- a/doc/source/cli/neutron.rst +++ /dev/null @@ -1,412 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - - Convention for heading levels in Neutron devref: - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - (Avoid deeper levels because they do not render well.) - -Using neutron CLI -================= - -The **neutron** shell utility interacts with OpenStack Networking API from the -command-line. It supports the entire features of OpenStack Networking API. - -.. warning:: - - neutron CLI is now deprecated and will be removed in the future. - Use openstack CLI instead. See `openstack CLI command list - <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__ - and :doc:`its extensions for advanced networking services <osc_plugins>`. - The command mapping from neutron CLI to openstack CLI is available - `here <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>`__. - -Basic Usage ------------ - -In order to use the CLI, you must provide your OpenStack username, password, -project, domain information for both user and project, and auth endpoint. Use -the corresponding configuration options (``--os-username``, ``--os-password``, -``--os-project-name``, ``--os-user-domain-id``, ``os-project-domain-id``, and -``--os-auth-url``), but it is easier to set them in environment variables. - -.. code-block:: shell - - export OS_USERNAME=user - export OS_PASSWORD=pass - export OS_PROJECT_NAME=project - export OS_USER_DOMAIN_ID=default - export OS_PROJECT_DOMAIN_ID=default - export OS_AUTH_URL=http://auth.example.com:5000/v3 - -If you are using Identity v2.0 API (DEPRECATED), you don't need to pass domain -information. - -.. code-block:: shell - - export OS_USERNAME=user - export OS_PASSWORD=pass - export OS_TENANT_NAME=tenant - export OS_AUTH_URL=http://auth.example.com:5000/v2.0 - -Once you've configured your authentication parameters, you can run **neutron** -commands. All commands take the form of: - -.. code-block:: none - - neutron <command> [arguments...] - -Run **neutron help** to get a full list of all possible commands, and run -**neutron help <command>** to get detailed help for that command. - -Using with os-client-config -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -`os-client-config <https://docs.openstack.org/os-client-config/latest/>`_ -provides more convenient way to manage a collection of client configurations -and you can easily switch multiple OpenStack-based configurations. - -To use os-client-config, you first need to prepare -``~/.config/openstack/clouds.yaml`` like the following. - -.. code-block:: yaml - - clouds: - devstack: - auth: - auth_url: http://auth.example.com:5000 - password: your-secret - project_domain_id: default - project_name: demo - user_domain_id: default - username: demo - identity_api_version: '3' - region_name: RegionOne - devstack-admin: - auth: - auth_url: http://auth.example.com:35357 - password: another-secret - project_domain_id: default - project_name: admin - user_domain_id: default - username: admin - identity_api_version: '3' - region_name: RegionOne - -Then, you need to specify a configuration name defined in the above clouds.yaml. - -.. code-block:: shell - - export OS_CLOUD=devstack - -For more detail information, see the -`os-client-config <https://docs.openstack.org/os-client-config/latest/>`_ -documentation. - -Using with keystone token -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The command-line tool will attempt to re-authenticate using your provided -credentials for every request. You can override this behavior by manually -supplying an auth token using ``--os-url`` and ``--os-auth-token``. You can -alternatively set these environment variables. - -.. code-block:: shell - - export OS_URL=http://neutron.example.org:9696/ - export OS_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 - -Using noauth mode -~~~~~~~~~~~~~~~~~ - -If neutron server does not require authentication, besides these two arguments -or environment variables (We can use any value as token.), we need manually -supply ``--os-auth-strategy`` or set the environment variable. - -.. code-block:: shell - - export OS_AUTH_STRATEGY=noauth - -Display options ---------------- - -Filtering -~~~~~~~~~ - -Neutron API supports filtering in the listing operation. -**neutron** CLI supports this feature too. - -To specify a filter in ``*-list`` command, you need to pass a pair of an -attribute name and an expected value with the format of ``--<attribute> <value>``. -The example below retrieves ports owned by compute instances. - -.. code-block:: console - - $ neutron port-list --device_owner network:dhcp - +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ - | id | name | mac_address | fixed_ips | - +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ - | 8953d683-29ad-4be3-b73f-060727c7849b | | fa:16:3e:4b:9e:0a | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.2"} | - | | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe4b:9e0a"} | - +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ - -You can also specify multiple filters. -The example below retrieves security group rules applied to IPv4 traffic -which belongs to a security group bfa493f9-2b03-46d2-8399-b9b038a53bc1. - -.. code-block:: console - - $ neutron security-group-rule-list --security-group-id bfa493f9-2b03-46d2-8399-b9b038a53bc1 --ethertype IPv4 - +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ - | id | security_group | direction | ethertype | protocol/port | remote | - +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ - | 65489805-0400-4bce-9bd9-16a81952263c | default | egress | IPv4 | any | any | - | 9429f336-4947-4643-bbd9-24528cc65648 | default | ingress | IPv4 | any | default (group) | - +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ - -.. note:: - - Looking up UUID from name is not supported when specifying a filter. - You need to use UUID to specify a specific resource. - -.. note:: - - Filtering for dictionary or list attributes is not supported. - -Changing displayed columns -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want displayed columns in a list operation, ``-c`` option can be used. -``-c`` can be specified multiple times and the column order will be same as -the order of ``-c`` options. - -.. code-block:: console - - $ neutron port-list -c id -c device_owner -c fixed_ips - +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ - | id | device_owner | fixed_ips | - +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ - | 41ca1b9b-4bbd-4aa8-bcaa-31d3d5704205 | network:router_interface | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.1"} | - | 8953d683-29ad-4be3-b73f-060727c7849b | network:dhcp | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.2"} | - | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe4b:9e0a"} | - | a9da29f8-4504-4526-a5ce-cd3624fbd173 | neutron:LOADBALANCER | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.3"} | - | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:feb1:ab71"} | - | d6a1ff96-0a99-416f-a4d6-65d9614cf64e | compute:nova | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.4"} | - | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe2c:348e"} | - | f4789225-26d0-409f-8047-82d2c7a87a95 | network:router_interface | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66::1"} | - +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ - -.. _cli_extra_arguments: - -Extra arguments for create/update operation -------------------------------------------- - -**neutron** CLI has a mechanism called the *extra arguments* for ``*-create`` -and ``*-update`` commands. It allows users to specify a set of *unknown -options* which are not defined as options and not shown in the help text. -**Unknown options MUST be placed at the end of the command line.** -*unknown options* will be directly passed to the API layer. By this mechanism, -you can pass an attribute which is not defined in the upstream **neutron** -CLI. For example, when you are developing a new feature which add a new -attribute to an existing resource, it is useful because we can test your -feature without changing the existing neutron CLI. - -For example, if you run the following command:: - - neutron resource-update <ID> --key1 value1 --key2 value2 - -where ``resource`` is some resource name and ``--key1`` and ``--key2`` are -unknown options, then the following JSON will be sent to the neutron API:: - - PUT /v2.0/resources/<ID> - - { - "resource": { - "key2": "value2", - "key1": "value1" - } - } - -Key interpretation -~~~~~~~~~~~~~~~~~~ - -This means an option name (``--key1`` in this case) must be one of valid -resources of a corresponding resource. An option name ``--foo_bar`` is -recognized as an attribute name ``foo_bar``. ``--foo-bar`` is also interpreted -as an attribute name ``foo_bar``. - -Value interpretation -~~~~~~~~~~~~~~~~~~~~ - -By default, if the number of values is 1, the option value is interpreted as a -string and is passed to the API layer as specified in a command-line. - -If the number of values is greater than 1, the option value is interpreted as a -list and the result in the API layer will be same as when specifying a list as -described below. - - neutron resource-update <ID> --key1 val1 val2 val3 --key2 val4 - -In the above example, a value of ``key1`` is interpreted as -``["val1", "val2", "val3"]`` and a value of ``key2`` is interpreted -as ``val4``. - -The extra argument mechanism supports more complex value like a list or a dict. - -Specify a list value -++++++++++++++++++++ - -A command-line:: - - neutron resource-update <ID> --key list=true val1 val2 val3 - -will send the following in the API layer:: - - { - "key": [ - "val1", - "val2", - "val3" - ] - } - -.. note:: - - If you want to specify a list value, it is recommended to specify - ``list=true``. When ``list=true`` is specified, specified values are - interpreted as a list even regardless of the number of values. - - If ``list=true`` is not specified, specified values are interpreted - depends on the number of values how. If the number of values is more than 2, - the specified values are interpreted as a list. If 1, the value - is interpreted as a string. - -Specify a dict value -++++++++++++++++++++ - -A command-line:: - - neutron resource-update <ID> --key type=dict key1=val1,key2=val2,key3=val3 - -will send the following in the API layer:: - - { - "key": { - "key1": "val1", - "key2": "val2", - "key3": "val3" - } - } - -.. note:: - - ``type=bool True/False`` and ``type=int 10`` are also supported. - -Specify a list of dicts -+++++++++++++++++++++++ - -A command-line:: - - neutron resource-update <ID> --key type=dict list=true key1=val1 key2=val2 key3=val3 - -will send the following in the API layer:: - - { - "key": [ - {"key1": "val1"}, - {"key2": "val2"}, - {"key3": "val3"} - ] - } - -Passing None as a value -~~~~~~~~~~~~~~~~~~~~~~~ - -There is a case where we would like to pass ``None`` (``null`` in JSON) -in the API layer. To do this:: - - neutron resource-update <ID> --key action=clear - -The following body will be in the API layer:: - - {"key": null} - -.. note:: - - If ``action=clear`` is specified, ``list=true`` or ``type=dict`` is ignored. - It means when ``action=clear`` is specified ``None`` is always sent. - -Debugging ---------- - -Display API-level communication -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``-v`` (or ``--verbose``, ``--debug``) option displays a detail interaction -with your neutron server. It is useful to debug what happens in the API level. - -Here is an sample output of ``net-show`` command. - -The first line show what parameters are recognized by neutronclient. -It is sometimes useful to check if command-line parameters you specify are recognized properly. - -.. code-block:: console - - $ neutron -v net-show mynetwork - DEBUG: neutronclient.neutron.v2_0.network.ShowNetwork get_data(Namespace(columns=[], fields=[], formatter='table', id=u'mynetwork', max_width=0, noindent=False, prefix='', request_format='json', show_details=False, variables=[])) - -Next, neutronclient sends an authentication request to keystone to get a token -which is used in further operations. - -.. code-block:: console - - DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:5000 -H "Accept: application/json" -H "User-Agent: keystoneauth1" - DEBUG: keystoneauth.session RESP: [300] Content-Length: 593 Vary: X-Auth-Token Keep-Alive: timeout=5, max=100 Server: Apache/2.4.7 (Ubuntu) Connection: Keep-Alive Date: Fri, 27 Nov 2015 20:10:54 GMT Content-Type: application/json - RESP BODY: {"versions": {"values": [{"status": "stable", "updated": "2015-03-30T00:00:00Z", "media-types": [{"base": "application/json", "type": "application/vnd.openstack.identity-v3+json"}], "id": "v3.4", "links": [{"href": "http://172.16.18.47:5000/v3/", "rel": "self"}]}, {"status": "stable", "updated": "2014-04-17T00:00:00Z", "media-types": [{"base": "application/json", "type": "application/vnd.openstack.identity-v2.0+json"}], "id": "v2.0", "links": [{"href": "http://172.16.18.47:5000/v2.0/", "rel": "self"}, {"href": "http://docs.openstack.org/", "type": "text/html", "rel": "describedby"}]}]}} - - DEBUG: keystoneauth.identity.v3.base Making authentication request to http://172.16.18.47:5000/v3/auth/tokens - -Neutronclient looks up a network ID corresponding to a given network name. - -.. code-block:: console - - DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:9696/v2.0/networks.json?fields=id&name=mynetwork -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: {SHA1}39300e7398d53a02afd183f13cb6afaef95ec4e5" - DEBUG: keystoneauth.session RESP: [200] Date: Fri, 27 Nov 2015 20:10:55 GMT Connection: keep-alive Content-Type: application/json; charset=UTF-8 Content-Length: 62 X-Openstack-Request-Id: req-ccebf6e4-4f52-4874-a1ab-5499abcba378 - RESP BODY: {"networks": [{"id": "3698d3c7-d581-443e-bf86-53c4e3a738f7"}]} - -Finally, neutronclient retrieves a detail of a given network using the resolved ID. - -.. code-block:: console - - DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:9696/v2.0/networks/3698d3c7-d581-443e-bf86-53c4e3a738f7.json -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: {SHA1}39300e7398d53a02afd183f13cb6afaef95ec4e5" - DEBUG: keystoneauth.session RESP: [200] Date: Fri, 27 Nov 2015 20:10:55 GMT Connection: keep-alive Content-Type: application/json; charset=UTF-8 Content-Length: 272 X-Openstack-Request-Id: req-261add00-d6d3-4ea7-becc-105b60ac7369 - RESP BODY: {"network": {"status": "ACTIVE", "subnets": [], "name": "mynetwork", "admin_state_up": true, "tenant_id": "8f0ebf767043483a987736c8c684178d", "mtu": 0, "router:external": false, "shared": false, "port_security_enabled": true, "id": "3698d3c7-d581-443e-bf86-53c4e3a738f7"}} - - +-----------------------+--------------------------------------+ - | Field | Value | - +-----------------------+--------------------------------------+ - | admin_state_up | True | - | id | 3698d3c7-d581-443e-bf86-53c4e3a738f7 | - | mtu | 0 | - | name | mynetwork | - | port_security_enabled | True | - | router:external | False | - | shared | False | - | status | ACTIVE | - | subnets | | - | tenant_id | 8f0ebf767043483a987736c8c684178d | - +-----------------------+--------------------------------------+ diff --git a/doc/source/contributor/cli_option_guideline.rst b/doc/source/contributor/cli_option_guideline.rst deleted file mode 100644 index 49a8405..0000000 --- a/doc/source/contributor/cli_option_guideline.rst +++ /dev/null @@ -1,263 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - - Convention for heading levels in Neutron devref: - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - (Avoid deeper levels because they do not render well.) - -CLI Option Guideline -==================== - -This document describes the conventions of neutron CLI options. - -General conventions -------------------- - -#. Option names should be delimited by a hyphen instead of a underscore. - This is the common guidelines across all OpenStack CLIs. - - * Good: ``--ip-version`` - * Not Good: ``--ip_version`` - -#. Use at least one required option for ``*-create`` command. If all options - are optional, we typically use ``name`` field as a required option. - -#. When you need to specify an ID of a resource, it is better to provide - another way to specify the resource like ``name`` or other reasonable field. - -#. If an attribute name in API is ``foo_id``, the corresponding option - should be ``--foo`` instead of ``--foo-id``. - - * It is because we usually support ID and ``name`` to specify a resource. - -#. Do not use ``nargs='?'`` without a special reason. - - * The behavior of ``nargs='?'`` option for python argparse is - bit tricky and may lead to unexpected option parsing different - from the help message. The detail is described in the - :ref:`Background section <background-nargs>` below. - -#. (option) Avoid using positional options as much as possible. - - * Positional arguments should be limited to attributes which will - be required in the long future. - -#. We honor existing options and should keep compatibilities when adding or - changing options. - -Options for boolean value -------------------------- - -Use the form of ``--option-name {True|False}``. - -* For a new option, it is recommended. -* It is suggested to use ``common.utils.add_boolean_argument`` in an - implementation. It allows ``true``/``false`` in addition to ``True``/``False``. -* For existing options, migration to the recommended form is not necessarily - required. All backward-compatibility should be kept without reasonable - reasons. - -Options for dict value ----------------------- - -Some API attributes take a dictionary. - -``--foo key1=val1,key2=val2`` is usually used. - -This means ``{"key1": "val1", "key2": "val2"}`` is passed in the API layer. - -Examples: - -* ``--host-route destination=CIDR,nexthop=IP_ADDR`` for a subnet -* ``--fixed-ip subnet_id=SUBNET,ip_address=IP_ADDR`` for a port. - -Options for list value ----------------------- - -Some attributes take a list. - -In this case, we usually use: - -* Define an option per element (Use a singular form as an option name) -* Allow to specify the option multiple times - -For Example, **port-create** has ``--security-group`` option. -``--security-group SG1 --security-group SG2`` generates -``{"security_groups: ["SG1", "SG2"]}`` in the API layer. - -This convention applies to a case of a list of dict. -``--allocation-pool`` and ``--host-route`` for a subnet are examples. - -Compatibility with extra arguments ----------------------------------- - -*extra arguments* supports various types of option specifications. -At least the following patterns needs to be considered when defining -a new option. For more detail, see :ref:`cli_extra_arguments`. - -* Normal options with value -* Boolean options : ``--foo True``, ``--bar=False`` -* List options : ``--bars list=true val1 val2``, ``--bars val1 val2`` -* Dict options : ``--foo type=dict key1=va1,key2=val2`` -* List of Dict options : ``--bars list=true type=dict key1=val1,key2=val2 key3=val3,key4=val4`` -* ``action=clear`` - -For normal options with value, there are four patterns to specify an option -as extra arguments. - -* ``--admin-state-up True`` (a space between option name and value) -* ``--admin-state-up=True`` (= between option name and value) -* ``--admin_state_up True`` (underscore is used as delimiter) -* ``--admin_state_up=True`` (underscore is used as delimiter) - -.. _background: - -Background ----------- - -There are a lot of opinions on which form of options are better or not. -This section tries to capture the reason of the current choice. - -Use at least one required option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As a convention, **neutron** CLI requires one required argument. - -If all options are optional in the API level and we have ``name`` field, -we usually use ``name`` as a required parameter. -Requiring at least one argument has the following benefits: - -* If we run ``neutron *-create`` without a required argument, we will have a - brief help message without detail option help. It is convenient. -* We can avoid miss operation by just hitting ``neutron *-create``. - Requiring at least one parameter is a good balance. - -Even though we can change this convention to allow to create a resource -without ``name`` field, it will bring confusions to existing users. - -There may be opinion that it is inconsistent with API level requirement -or Horizon behavior, but even if neutron CLI requires ``name`` field -there is no bad impact on regular users. Considering possible confusion -if we change it, it looks better to keep it as-is. - -Options for Boolean value -~~~~~~~~~~~~~~~~~~~~~~~~~ - -* ``--enable-foo``/``--disable-foo`` or similar patterns (including - ``--admin-state-down``) is not suggested because we need two exclusive - options for one attribute in REST API. It is meaningless. - -* It is not recommended to have an option only to specify non-default value. - For example, we have ``--shared`` or ``--admin-state-down`` options for - net-create. This form only works for ``*-create`` and does not work for - ``*-update``. It leads to having different options for ``*-create`` and - ``*-update``. - -* A flag option like ``--enable-dhcp`` (without value) also has a problem when - considering the compatibility with *extra argument*. We can specify - ``-enable-dhcp True/False`` or ``--enable-dhcp=True/False`` in the *extra - argument* mechanism. If we introduce ``--enable-dhcp`` (without value), - the form of ``-enable-dhcp True/False`` cannot be used now. - This is another reason we don't use a flag style option for a boolean parameter. - -.. _background-nargs: - -Avoid using nargs in positional or optional arguments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The behavior of ``nargs='?'`` option for python argparse is bit tricky. -When we use ``nargs='?'`` and if the order of command-line options is -changed then the command-line parser may fail to parse the arguments -correctly. Two examples of such failures are provided below. - -Example 1: -This example shows how the actual behavior can differ from the provided -help message. In the below block, help message at ``[5]`` says ``--bb CC`` -is a valid format but the argument parsing for the same format fails at ``[7]``. - -.. code-block:: console - - In [1]: import argparse - In [2]: parser = argparse.ArgumentParser() - In [3]: parser.add_argument('--bb', nargs='?') - In [4]: parser.add_argument('cc') - - In [5]: parser.print_help() - usage: ipython [-h] [--bb [BB]] cc - - positional arguments: - cc - - optional arguments: - -h, --help show this help message and exit - --bb [BB] - - In [6]: parser.parse_args('--bb 1 X'.split()) - Out[6]: Namespace(bb='1', cc='X') - - In [7]: parser.parse_args('--bb X'.split()) - usage: ipython [-h] [--bb [BB]] cc - ipython: error: too few arguments - An exception has occurred, use %tb to see the full traceback. - - SystemExit: 2 - - -Example 2: -This example shows how fragile ``nargs='?'`` can be when user specifies -options in different order from the help message. - -.. code-block:: console - - In [1]: import argparse - In [2]: parser = argparse.ArgumentParser() - In [3]: parser.add_argument('--a', help='option a') - In [4]: parser.add_argument('--b', help='option b') - In [5]: parser.add_argument('x', help='positional arg X') - In [6]: parser.add_argument('y', nargs='?', help='positional arg Y') - In [7]: parser.print_help() - usage: ipython [-h] [--a A] [--b B] x [y] - - positional arguments: - x positional arg X - y positional arg Y - - optional arguments: - -h, --help show this help message and exit - --a A option a - --b B option b - - In [8]: parser.parse_args('--a 1 --b 2 X Y'.split()) - Out[8]: Namespace(a='1', b='2', x='X', y='Y') - - In [9]: parser.parse_args('X Y --a 1 --b 2'.split()) - Out[9]: Namespace(a='1', b='2', x='X', y='Y') - - In [10]: parser.parse_args('X --a 1 --b 2 Y'.split()) - usage: ipython [-h] [--a A] [--b B] x [y] - ipython: error: unrecognized arguments: Y - An exception has occurred, use %tb to see the full traceback. - - SystemExit: 2 - - To exit: use 'exit', 'quit', or Ctrl-D. - To exit: use 'exit', 'quit', or Ctrl-D. - -Note: Most CLI users don't care about the order of the command-line -options. Hence, such fragile behavior should be avoided. - diff --git a/doc/source/contributor/client_command_extensions.rst b/doc/source/contributor/client_command_extensions.rst deleted file mode 100644 index 4b74cdf..0000000 --- a/doc/source/contributor/client_command_extensions.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - - Convention for heading levels in Neutron devref: - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - (Avoid deeper levels because they do not render well.) - -Client command extension support -================================= - -The client command extension adds support for extending the neutron client while -considering ease of creation. -Extensions strongly conform to preexisting neutron commands (/neutron/v2_0/). - -A sample extension can be seen at: -neutronclient/neutron/v2_0/contrib/_fox_sockets.py - -Minimum requirements from an extension --------------------------------------- - -* NeutronClientExtension subclasses must have a shell_command class variable - if the command is to be available to the CLI (shell.py) - - Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsList - -Minimum requirements to use canonical neutron CRUD commands framework ----------------------------------------------------------------------- - -Neutron commands are cliff commands, commands in extension can use their -own way to finish their tasks. But if they want to make use of the canonical -neutron CRUD commands framework, the extension should: - -* have a class that subclasses NeutronClientExtension to provide the - requisite resource name, version support, and resource collection and - object paths for a resource the commands will process. - - Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocket - -* have a class that subclasses from the ClientExtensionList to provide - resource object list function. This is because most commands - need the list function to get object ID via - neutronclient.neutron.v2_0.__init__.find_resource_by_id. - - Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsList - -* if needed, subclass ClientExtensionUpdate to implement update of the resource - object. - - Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsUpdate - -* if needed, subclass ClientExtensionDelete to implement deletion of the resource - object. - - Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsDelete - -* if needed, subclass ClientExtensionShow to get the detail of the resource - object. - - Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsShow - -Precedence of command loading ------------------------------- - -* hard coded commands are loaded first -* external commands (installed in the environment) are loaded then - -Commands that have the same name will be overwritten by commands that are -loaded later. To change the execution of a command for your particular -extension you only need to override the execute method. - -Currently this extension support is limited to top-level resources. -Parent/child relationships may be added if desired. - -neutronclient.extension entry_point ------------------------------------ - -To activate the commands in a specific extension module, add an entry in -setup.cfg under neutronclient.extension. For example:: - - [entry_points] - neutronclient.extension = - fox_sockets = neutronclient.neutron.v2_0.contrib._fox_sockets diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index f2150b0..fae3f6b 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -31,6 +31,4 @@ OpenStack client. .. toctree:: :maxdepth: 2 - client_command_extensions - cli_option_guideline transition_to_osc diff --git a/doc/source/contributor/transition_to_osc.rst b/doc/source/contributor/transition_to_osc.rst index 334f2e5..9bb9529 100644 --- a/doc/source/contributor/transition_to_osc.rst +++ b/doc/source/contributor/transition_to_osc.rst @@ -105,7 +105,7 @@ Transition Steps 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. -8. **Not Started:** Remove the ``neutron`` CLI after two deprecation cycles +8. **Done** Remove the ``neutron`` CLI after two deprecation cycles once the criteria below have been met. * The networking support provide by the ``openstack`` CLI is functionally @@ -122,32 +122,8 @@ Transition Steps Developer Guide --------------- -The ``neutron`` CLI version 6.x, without extensions, supports over 200 -commands while the ``openstack`` CLI version 3.3.0 supports over 70 -networking commands. Of the 70 commands, some do not have all of the options -or arguments of their ``neutron`` CLI equivalent. With this large functional -gap, a few critical questions for developers during this transition are "Which -CLI do I change?", "Where does my CLI belong?", and "Which Python library do I change?" -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. - -**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`` | -+----------------------+------------------------+-------------------------------------------------+ +The ``neutron`` CLI tool is now removed and all new CLI changes should be done +in the ``OpenStackClient (OSC)`` and, if needed, also in the ``OpenStack SDK``. **Where does my CLI belong?** @@ -186,8 +162,6 @@ is not required as the neutronclient is already deprecated on its own. +=================================================+===============================================+ | python-openstackclient | openstacksdk | +-------------------------------------------------+-----------------------------------------------+ -| python-neutronclient | python-neutronclient | -+-------------------------------------------------+-----------------------------------------------+ | Other | Applicable project owning network resource | +-------------------------------------------------+-----------------------------------------------+ diff --git a/doc/source/index.rst b/doc/source/index.rst index 64ad45a..c36d482 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -24,15 +24,11 @@ python-neutronclient documentation ================================== This is a client for OpenStack Networking API. It provides -:doc:`Python API bindings <reference/index>` (the neutronclient module) and -:doc:`command-line interface (CLI) <cli/index>`. +:doc:`Python API bindings <reference/index>` (the neutronclient module). -There are two CLIs which support the Networking API: -:doc:`neutron CLI <cli/neutron>` and +There is `OpenStack Client (OSC) <https://docs.openstack.org/python-openstackclient/latest/>`__. -OpenStack Client provides the basic network commands and -python-neutronclient provides extensions (aka OSC plugins) -for advanced networking services. +CLI which support the Networking API. User Documentation ------------------ |