api-ref: document network-segment-range extension

API definition of network-segment-range extension in neutron-lib:
* https://review.openstack.org/626500

Co-authored-by: Allain Legacy <Allain.legacy@windriver.com>

Partially-implements: blueprint network-segment-range-management
Change-Id: I36bca4b1067abcc7db7c94dd36a6a4da62a6aab1
This commit is contained in:
Kailun Qin 2018-12-26 06:29:56 +08:00
parent 6bbac3c726
commit 4398fd5bf6
9 changed files with 494 additions and 0 deletions

View File

@ -17,6 +17,7 @@ General API Overview
Layer 2 Networking
##################
.. include:: networks.inc
.. include:: network_segment_ranges.inc
.. include:: ports.inc
.. include:: segments.inc
.. include:: trunk.inc

View File

@ -0,0 +1,245 @@
.. -*- rst -*-
======================
Network Segment Ranges
======================
The network segment range extension exposes the segment range management to be
administered via the Neutron API. It introduces the `network-segment-range`
resource for tenant network segment allocation. In addition, it introduces
the ability for the administrator to control the segment ranges globally or on
a per-tenant basis.
Lists, shows details for, creates, updates, and deletes network segment ranges.
The network segment ranges API is admin-only.
Show network segment range details
==================================
.. rest_method:: GET /v2.0/network_segment_ranges/{network_segment_range_id}
Shows details for a network segment range.
You can control which response parameters are returned by using the
fields query parameter. For information, see `Filtering and column
selection <http://specs.openstack.org/openstack/neutron-
specs/specs/api/networking_general_api_information.html#filtering-
and-column-selection>`__.
Normal response codes: 200
Error response codes: 401, 404
Request
-------
.. rest_parameters:: parameters.yaml
- network_segment_range_id: network_segment_range_id-path
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: network_segment_range_id
- name: name
- default: network_segment_range-default
- shared: network_segment_range-shared
- tenant_id: project_id
- project_id: project_id
- network_type: network_segment_range-network_type
- physical_network: network_segment_range-physical_network-body-required
- minimum: network_segment_range-minimum-body-required
- maximum: network_segment_range-maximum-body-required
- available: network_segment_range-available
- used: network_segment_range-used
Response Example
----------------
.. literalinclude:: samples/network_segment_ranges/network_segment_range-show-response.json
:language: javascript
Update network segment range
============================
.. rest_method:: PUT /v2.0/network_segment_ranges/{network_segment_range_id}
Updates a network segment range.
Normal response codes: 200
Error response codes: 400, 401, 403, 404, 412
Request
-------
.. rest_parameters:: parameters.yaml
- network_segment_range_id: network_segment_range_id-path
- name: name-request
- minimum: network_segment_range-minimum-body-optional
- maximum: network_segment_range-maximum-body-optional
Request Example
---------------
.. literalinclude:: samples/network_segment_ranges/network_segment_range-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: network_segment_range_id
- name: name
- default: network_segment_range-default
- shared: network_segment_range-shared
- tenant_id: project_id
- project_id: project_id
- network_type: network_segment_range-network_type
- physical_network: network_segment_range-physical_network-body-required
- minimum: network_segment_range-minimum-body-required
- maximum: network_segment_range-maximum-body-required
- available: network_segment_range-available
- used: network_segment_range-used
Response Example
----------------
.. literalinclude:: samples/network_segment_ranges/network_segment_range-update-response.json
:language: javascript
Delete network segment range
============================
.. rest_method:: DELETE /v2.0/network_segment_ranges/{network_segment_range_id}
Deletes a network segment range.
Normal response codes: 204
Error response codes: 401, 404, 409, 412
Request
-------
.. rest_parameters:: parameters.yaml
- network_segment_range_id: network_segment_range_id-path
Response
--------
There is no body content for the response of a successful DELETE request.
List network segment ranges
===========================
.. rest_method:: GET /v2.0/network_segment_ranges
Lists network segment ranges to which the admin has access.
Use the ``fields`` query parameter to filter the response. For
information, see `Filtering and Column Selection <https://wiki.open
stack.org/wiki/Neutron/APIv2-specification#Filtering_and_Column_Sel
ection>`__.
Normal response codes: 200
Error response codes: 401
Request
-------
.. rest_parameters:: parameters.yaml
- id: network_segment_range_id-query
- name: network_segment_range-name-query
- tenant_id: project_id-query
- project_id: project_id-query
- network_type: network_segment_range-network_type-query
- physical_network: network_segment_range-physical_network-query
- sort_dir: sort_dir
- sort_key: network_segment_range-sort_key
- fields: fields
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: network_segment_range_id
- name: name
- default: network_segment_range-default
- shared: network_segment_range-shared
- tenant_id: project_id
- project_id: project_id
- network_type: network_segment_range-network_type
- physical_network: network_segment_range-physical_network-body-required
- minimum: network_segment_range-minimum-body-required
- maximum: network_segment_range-maximum-body-required
- available: network_segment_range-available
- used: network_segment_range-used
Response Example
----------------
.. literalinclude:: samples/network_segment_ranges/network_segment_ranges-list-response.json
:language: javascript
Create network segment range
============================
.. rest_method:: POST /v2.0/network_segment_ranges
Creates a network segment range.
Normal response codes: 201
Error response codes: 400, 401
Request
-------
.. rest_parameters:: parameters.yaml
- name: network_segment_range-name
- shared: network_segment_range-shared
- project_id: project_id-body-optional
- network_type: network_segment_range-network_type
- physical_network: network_segment_range-physical_network-body-optional
- minimum: network_segment_range-minimum-body-required
- maximum: network_segment_range-minimum-body-required
Request Example
---------------
.. literalinclude:: samples/network_segment_ranges/network_segment_range-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: network_segment_range_id
- name: name
- default: network_segment_range-default
- shared: network_segment_range-shared
- tenant_id: project_id
- project_id: project_id
- network_type: network_segment_range-network_type
- physical_network: network_segment_range-physical_network-body-required
- minimum: network_segment_range-minimum-body-required
- maximum: network_segment_range-maximum-body-required
- available: network_segment_range-available
- used: network_segment_range-used
Response Example
----------------
.. literalinclude:: samples/network_segment_ranges/network_segment_range-create-response.json
:language: javascript

View File

@ -187,6 +187,12 @@ network_id-path:
in: path
required: true
type: string
network_segment_range_id-path:
description: |
The ID of the network segment range.
in: path
required: true
type: string
pool_id-path:
description: |
The ID for the pool.
@ -811,6 +817,47 @@ network_is_default-query:
in: query
required: false
type: boolean
network_segment_range-name-query:
description: |
Filter the network segment range list result based on the name of the
range.
in: query
required: false
type: string
network_segment_range-network_type-query:
description: |
Filter the list result by the type of physical network that this
network segment range is mapped to. For example, ``vlan``, ``vxlan``, or
``gre``. Valid values depend on a networking back-end.
in: query
required: false
type: string
network_segment_range-physical_network-query:
description: |
Filter the list result by the physical network where this
network segment range is implemented.
in: query
required: false
type: string
network_segment_range-sort_key:
description: |
Sorts by a network segment range attribute. You can specify multiple pairs
of sort key and sort direction query parameters. The sort keys are limited
to:
- ``id``
- ``name``
- ``project_id``
- ``tenant_id``
in: query
required: false
type: string
network_segment_range_id-query:
description: |
Filter the network segment range list result based on the range ID.
in: query
required: false
type: string
not-tags-any-query:
description: |
A list of tags to filter the list result by.
@ -842,6 +889,13 @@ object_type-query:
in: query
required: false
type: string
physical_network-query:
description: |
Filter the list result by the physical network where this
network/segment is implemented.
in: query
required: false
type: string
port-sort_key:
description: |
Sorts by a port attribute. You can specify multiple pairs of sort key
@ -4116,6 +4170,88 @@ network_is_default-request:
in: body
required: false
type: boolean
network_segment_range-available:
description: |
List of available segmentation IDs in the network segment range.
in: body
required: true
type: list
network_segment_range-default:
description: |
Defines whether the network segment range is the default that is loaded
from the host ML2 config file.
in: body
required: true
type: boolean
network_segment_range-maximum-body-optional:
description: |
The maximum segmentation ID of the network segment range.
in: body
required: false
type: integer
network_segment_range-maximum-body-required:
description: |
The maximum segmentation ID of the network segment range.
in: body
required: true
type: integer
network_segment_range-minimum-body-optional:
description: |
The minimum segmentation ID of the network segment range.
in: body
required: false
type: integer
network_segment_range-minimum-body-required:
description: |
The minimum segmentation ID of the network segment range.
in: body
required: true
type: integer
network_segment_range-name:
description: |
Human-readable name of the network segment range.
in: body
required: false
type: string
network_segment_range-network_type:
description: |
The type of physical network that maps to this network segment range
resource. For example, ``vlan``, ``vxlan``, or ``gre``. Valid values depend
on a networking back-end.
in: body
required: true
type: string
network_segment_range-physical_network-body-optional:
description: |
The physical network where this network segment range is implemented.
in: body
required: false
type: string
network_segment_range-physical_network-body-required:
description: |
The physical network where this network segment range is implemented.
in: body
required: true
type: string
network_segment_range-shared:
description: |
Indicates whether this network segment range is shared across all projects.
in: body
required: true
type: boolean
network_segment_range-used:
description: |
Mapping of which segmentation ID in the network segment range is used by
which project.
in: body
required: true
type: dict
network_segment_range_id:
description: |
The UUID of the network segment range.
in: body
required: true
type: string
network_type:
description: |
The type of physical network that maps to this
@ -4201,6 +4337,12 @@ phase1_negotiation_mode:
in: body
required: false
type: string
physical_network:
description: |
The physical network where this network/segment is implemented.
in: body
required: false
type: string
policies:
description: |
A list of QoS ``policy`` objects.

View File

@ -0,0 +1,11 @@
{
"network_segment_range": {
"name": "range_vlan_physnet1",
"shared": false,
"project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"network_type": "vlan",
"physical_network": "physnet1",
"minimum": 10,
"maximum": 20
}
}

View File

@ -0,0 +1,16 @@
{
"network_segment_range": {
"id": "59b38ee8-6642-418a-88b7-756861606ecb",
"name": "range_vlan_physnet1",
"default": false,
"shared": false,
"tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"network_type": "vlan",
"physical_network": "physnet1",
"minimum": 10,
"maximum": 20,
"available": [10,11,12,13,14,15,16,17,18,19,20],
"used": {}
}
}

View File

@ -0,0 +1,18 @@
{
"network_segment_range": {
"id": "59b38ee8-6642-418a-88b7-756861606ecb",
"name": "range_vlan_physnet1",
"default": false,
"shared": false,
"tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"network_type": "vlan",
"physical_network": "physnet1",
"minimum": 10,
"maximum": 20,
"available": [10,11,12,13,14,15,16,19,20],
"used": {
"17": "5fc1cd2f16ab4c8fbba2e780891b9de3",
"18": "87504c1c9d86439882ff90fdbfb096ad"}
}
}

View File

@ -0,0 +1,7 @@
{
"network_segment_range": {
"name": "new_range",
"minimum": 10,
"maximum": 20
}
}

View File

@ -0,0 +1,18 @@
{
"network_segment_range": {
"id": "50089a13-4a9f-4421-85ba-5222e84610c3",
"name": "new_range",
"default": false,
"shared": false,
"tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"network_type": "vxlan",
"physical_network": null,
"minimum": 10,
"maximum": 20,
"available": [10,11,12,13,14,15,16,19,20],
"used": {
"17": "5fc1cd2f16ab4c8fbba2e780891b9de3",
"18": "87504c1c9d86439882ff90fdbfb096ad"}
}
}

View File

@ -0,0 +1,36 @@
{
"network_segment_ranges": [
{
"id": "59b38ee8-6642-418a-88b7-756861606ecb",
"name": "range_vlan_physnet1",
"default": false,
"shared": false,
"tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
"network_type": "vlan",
"physical_network": "physnet1",
"minimum": 10,
"maximum": 20,
"available": [10,11,12,13,14,15,16,19,20],
"used": {
"17": "5fc1cd2f16ab4c8fbba2e780891b9de3",
"18": "87504c1c9d86439882ff90fdbfb096ad"}
},
{
"id": "91ea6e31-3a6d-4541-8432-b49b4cacf893",
"name": "range_vxlan",
"default": false,
"shared": true,
"tenant_id": null,
"project_id": null,
"network_type": "vxlan",
"physical_network": null,
"minimum": 40,
"maximum": 50,
"available": [40,41,43,44,46,47,48,49,50],
"used": {
"42": "07ac1127ee9647d48ce2626867104a13",
"45": "d4fa62aa47d340d98d076801aa7e6ec4"}
}
]
}