diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index d9b18c1c0..ef0c673f2 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -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 diff --git a/api-ref/source/v2/network_segment_ranges.inc b/api-ref/source/v2/network_segment_ranges.inc new file mode 100644 index 000000000..1e0b381f7 --- /dev/null +++ b/api-ref/source/v2/network_segment_ranges.inc @@ -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 `__. + +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 `__. + +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 diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 44761a2b5..49499b4f4 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -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. diff --git a/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-create-request.json b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-create-request.json new file mode 100644 index 000000000..be0b9f543 --- /dev/null +++ b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-create-request.json @@ -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 + } +} diff --git a/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-create-response.json b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-create-response.json new file mode 100644 index 000000000..b47bf22bf --- /dev/null +++ b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-create-response.json @@ -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": {} + } +} diff --git a/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-show-response.json b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-show-response.json new file mode 100644 index 000000000..d2df00a7c --- /dev/null +++ b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-show-response.json @@ -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"} + } +} diff --git a/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-update-request.json b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-update-request.json new file mode 100644 index 000000000..cd96aff86 --- /dev/null +++ b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-update-request.json @@ -0,0 +1,7 @@ +{ + "network_segment_range": { + "name": "new_range", + "minimum": 10, + "maximum": 20 + } +} diff --git a/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-update-response.json b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-update-response.json new file mode 100644 index 000000000..b31c65f0b --- /dev/null +++ b/api-ref/source/v2/samples/network_segment_ranges/network_segment_range-update-response.json @@ -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"} + } +} diff --git a/api-ref/source/v2/samples/network_segment_ranges/network_segment_ranges-list-response.json b/api-ref/source/v2/samples/network_segment_ranges/network_segment_ranges-list-response.json new file mode 100644 index 000000000..e935ec58c --- /dev/null +++ b/api-ref/source/v2/samples/network_segment_ranges/network_segment_ranges-list-response.json @@ -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"} + } + ] +}