From ee74cb2a5ccdc13e8bf137d7387f01c6b202c150 Mon Sep 17 00:00:00 2001 From: Carlos Goncalves Date: Tue, 24 Jan 2017 21:52:27 +0000 Subject: [PATCH] API definition and reference for data plane status extension Related-Bug: #1598081 Related-Bug: #1575146 Partial-Implements: blueprint port-data-plane-status Change-Id: I04eef902b3310f799b1ce7ea44ed7cf77c74da04 --- api-ref/source/v2/parameters.yaml | 12 +++ api-ref/source/v2/ports.inc | 26 +++++++ .../extensions/extensions-list-response.json | 7 ++ .../ports/port-bind-create-response.json | 1 + .../ports/port-bind-show-response.json | 1 + .../ports/port-bind-update-request.json | 1 + .../ports/port-bind-update-response.json | 1 + .../samples/ports/port-create-response.json | 1 + .../v2/samples/ports/port-show-response.json | 1 + .../samples/ports/port-update-response.json | 1 + .../ports/ports-bind-list-response.json | 2 + .../ports/ports-bulk-create-response.json | 2 + .../v2/samples/ports/ports-list-response.json | 2 + neutron_lib/api/definitions/base.py | 1 + .../api/definitions/data_plane_status.py | 78 +++++++++++++++++++ .../api/definitions/test_data_plane_status.py | 22 ++++++ ...ata-plane-status-ext-c3452a01ef5007ce.yaml | 4 + 17 files changed, 163 insertions(+) create mode 100644 neutron_lib/api/definitions/data_plane_status.py create mode 100644 neutron_lib/tests/unit/api/definitions/test_data_plane_status.py create mode 100644 releasenotes/notes/data-plane-status-ext-c3452a01ef5007ce.yaml diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 1b163f822..018aaed23 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -935,6 +935,18 @@ created_at_resource: in: body required: true type: string +data_plane_status: + description: | + Status of the underlying data plane of a port. + in: body + required: true + type: string +data_plane_status-request: + description: | + Status of the underlying data plane of a port. + in: body + required: false + type: string default: description: | Defines whether the provider is the default for diff --git a/api-ref/source/v2/ports.inc b/api-ref/source/v2/ports.inc index 869be5887..0af4fe8fe 100644 --- a/api-ref/source/v2/ports.inc +++ b/api-ref/source/v2/ports.inc @@ -17,6 +17,22 @@ The extension defines several attributes whose names have a prefix | +Data plane status extension +=========================== + +The data plane port extension (``data-plane-status``) adds a new attribute +``data_plane_status`` to represent the status of the underlying data plane. +This attribute is to be managed by entities outside of the Networking service, +while the ``status`` attribute is managed by Networking service. Both status +attributes are independent from one another. + +Supported data plane status values: + +- ``null``: no status being reported; default value +- ``ACTIVE``: the underlying data plane is up and running +- ``DOWN``: no traffic can flow from/to the port + + Show port details ================= @@ -56,6 +72,7 @@ Response Parameters - binding:vif_type: binding:vif_type - binding:vnic_type: binding:vnic_type - created_at: created_at + - data_plane_status: data_plane_status - description: description - device_id: device_id - device_owner: device_owner @@ -108,6 +125,10 @@ specify it in the request body. If the security groups are not valid, the operation fails and the existing security groups are not removed from the port. +Only admins and users with a specific role can update the data plane status +(default role: ``data_plane_integrator``). + + Normal response codes: 200 Error response codes: 400, 401, 403, 404, 409 @@ -124,6 +145,7 @@ Request - binding:host_id: binding:host_id-request - binding:profile: binding:profile-request - binding:vnic_type: binding:vnic_type-request + - data_plane_status: data_plane_status-request - description: description-request - device_id: device_id-request - device_owner: device_owner-request @@ -160,6 +182,7 @@ Response Parameters - binding:vif_type: binding:vif_type - binding:vnic_type: binding:vnic_type - created_at: created_at + - data_plane_status: data_plane_status - description: description - device_id: device_id - device_owner: device_owner @@ -256,6 +279,7 @@ Response Parameters - binding:vif_type: binding:vif_type - binding:vnic_type: binding:vnic_type - created_at: created_at + - data_plane_status: data_plane_status - description: description - device_id: device_id - device_owner: device_owner @@ -348,6 +372,7 @@ Response Parameters - binding:vif_type: binding:vif_type - binding:vnic_type: binding:vnic_type - created_at: created_at + - data_plane_status: data_plane_status - description: description - device_id: device_id - device_owner: device_owner @@ -433,6 +458,7 @@ Response Parameters - binding:vif_type: binding:vif_type - binding:vnic_type: binding:vnic_type - created_at: created_at + - data_plane_status: data_plane_status - description: description - device_id: device_id - device_owner: device_owner diff --git a/api-ref/source/v2/samples/extensions/extensions-list-response.json b/api-ref/source/v2/samples/extensions/extensions-list-response.json index ee41ae6c9..b8c7400d5 100644 --- a/api-ref/source/v2/samples/extensions/extensions-list-response.json +++ b/api-ref/source/v2/samples/extensions/extensions-list-response.json @@ -118,6 +118,13 @@ "links": [], "alias": "extraroute", "description": "Extra routes configuration for L3 router" + }, + { + "updated": "2016-01-24T10:00:00-00:00", + "name": "Neutron Port Data Plane Status", + "links": [], + "alias": "data-plane-status", + "description": "Status of the underlying data plane." } ] } diff --git a/api-ref/source/v2/samples/ports/port-bind-create-response.json b/api-ref/source/v2/samples/ports/port-bind-create-response.json index e535df06c..49aa8b69c 100644 --- a/api-ref/source/v2/samples/ports/port-bind-create-response.json +++ b/api-ref/source/v2/samples/ports/port-bind-create-response.json @@ -15,6 +15,7 @@ "binding:vif_details": {}, "binding:vif_type": "unbound", "binding:vnic_type": "other", + "data_plane_status": null, "description": "", "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2", "device_owner": "baremetal:none", diff --git a/api-ref/source/v2/samples/ports/port-bind-show-response.json b/api-ref/source/v2/samples/ports/port-bind-show-response.json index f406e8c38..24961d5ab 100644 --- a/api-ref/source/v2/samples/ports/port-bind-show-response.json +++ b/api-ref/source/v2/samples/ports/port-bind-show-response.json @@ -11,6 +11,7 @@ "binding:vif_type": "ovs", "binding:vnic_type": "normal", "created_at": "2016-03-08T20:19:41", + "data_plane_status": "ACTIVE", "description": "", "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e", "device_owner": "network:router_interface", diff --git a/api-ref/source/v2/samples/ports/port-bind-update-request.json b/api-ref/source/v2/samples/ports/port-bind-update-request.json index 0dc052a36..4118974ef 100644 --- a/api-ref/source/v2/samples/ports/port-bind-update-request.json +++ b/api-ref/source/v2/samples/ports/port-bind-update-request.json @@ -2,6 +2,7 @@ "port": { "binding:host_id": "test_for_port_update_host", "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2", + "data_plane_status": "DOWN", "device_owner": "compute:nova" } } diff --git a/api-ref/source/v2/samples/ports/port-bind-update-response.json b/api-ref/source/v2/samples/ports/port-bind-update-response.json index 61b98f96c..a515f305a 100644 --- a/api-ref/source/v2/samples/ports/port-bind-update-response.json +++ b/api-ref/source/v2/samples/ports/port-bind-update-response.json @@ -7,6 +7,7 @@ "binding:vif_details": {}, "binding:vif_type": "binding_failed", "binding:vnic_type": "normal", + "data_plane_status": "DOWN", "description": "", "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2", "device_owner": "compute:nova", diff --git a/api-ref/source/v2/samples/ports/port-create-response.json b/api-ref/source/v2/samples/ports/port-create-response.json index 3076cfb29..3d64312c1 100644 --- a/api-ref/source/v2/samples/ports/port-create-response.json +++ b/api-ref/source/v2/samples/ports/port-create-response.json @@ -3,6 +3,7 @@ "admin_state_up": true, "allowed_address_pairs": [], "created_at": "2016-03-08T20:19:41", + "data_plane_status": null, "description": "", "device_id": "", "device_owner": "", diff --git a/api-ref/source/v2/samples/ports/port-show-response.json b/api-ref/source/v2/samples/ports/port-show-response.json index f95996f00..1469d71bf 100644 --- a/api-ref/source/v2/samples/ports/port-show-response.json +++ b/api-ref/source/v2/samples/ports/port-show-response.json @@ -3,6 +3,7 @@ "admin_state_up": true, "allowed_address_pairs": [], "created_at": "2016-03-08T20:19:41", + "data_plane_status": "ACTIVE", "description": "", "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e", "device_owner": "network:router_interface", diff --git a/api-ref/source/v2/samples/ports/port-update-response.json b/api-ref/source/v2/samples/ports/port-update-response.json index 61b98f96c..22a0a7de6 100644 --- a/api-ref/source/v2/samples/ports/port-update-response.json +++ b/api-ref/source/v2/samples/ports/port-update-response.json @@ -7,6 +7,7 @@ "binding:vif_details": {}, "binding:vif_type": "binding_failed", "binding:vnic_type": "normal", + "data_plane_status": "ACTIVE", "description": "", "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2", "device_owner": "compute:nova", diff --git a/api-ref/source/v2/samples/ports/ports-bind-list-response.json b/api-ref/source/v2/samples/ports/ports-bind-list-response.json index 884350fde..d4ea09fd1 100644 --- a/api-ref/source/v2/samples/ports/ports-bind-list-response.json +++ b/api-ref/source/v2/samples/ports/ports-bind-list-response.json @@ -11,6 +11,7 @@ }, "binding:vif_type": "ovs", "binding:vnic_type": "normal", + "data_plane_status": null, "description": "", "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824", "device_owner": "network:router_gateway", @@ -42,6 +43,7 @@ }, "binding:vif_type": "ovs", "binding:vnic_type": "normal", + "data_plane_status": null, "description": "", "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824", "device_owner": "network:router_interface", diff --git a/api-ref/source/v2/samples/ports/ports-bulk-create-response.json b/api-ref/source/v2/samples/ports/ports-bulk-create-response.json index 586a9ca67..6bc894b1a 100644 --- a/api-ref/source/v2/samples/ports/ports-bulk-create-response.json +++ b/api-ref/source/v2/samples/ports/ports-bulk-create-response.json @@ -3,6 +3,7 @@ { "admin_state_up": false, "allowed_address_pairs": [], + "data_plane_status": null, "description": "", "device_id": "", "device_owner": "", @@ -26,6 +27,7 @@ { "admin_state_up": false, "allowed_address_pairs": [], + "data_plane_status": null, "description": "", "device_id": "", "device_owner": "", diff --git a/api-ref/source/v2/samples/ports/ports-list-response.json b/api-ref/source/v2/samples/ports/ports-list-response.json index 985c760d4..b44f3a27b 100644 --- a/api-ref/source/v2/samples/ports/ports-list-response.json +++ b/api-ref/source/v2/samples/ports/ports-list-response.json @@ -3,6 +3,7 @@ { "admin_state_up": true, "allowed_address_pairs": [], + "data_plane_status": null, "description": "", "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824", "device_owner": "network:router_gateway", @@ -25,6 +26,7 @@ { "admin_state_up": true, "allowed_address_pairs": [], + "data_plane_status": null, "description": "", "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824", "device_owner": "network:router_interface", diff --git a/neutron_lib/api/definitions/base.py b/neutron_lib/api/definitions/base.py index 6fbcbfa9c..38f183cae 100644 --- a/neutron_lib/api/definitions/base.py +++ b/neutron_lib/api/definitions/base.py @@ -44,6 +44,7 @@ KNOWN_EXTENSIONS = ( 'auto-allocated-topology', 'availability_zone', 'binding', + 'data-plane-status', 'default-subnetpools', 'dhcp_agent_scheduler', 'dns-integration', diff --git a/neutron_lib/api/definitions/data_plane_status.py b/neutron_lib/api/definitions/data_plane_status.py new file mode 100644 index 000000000..5bcbf604d --- /dev/null +++ b/neutron_lib/api/definitions/data_plane_status.py @@ -0,0 +1,78 @@ +# Copyright (c) 2017 NEC Corporation. All rights reserved. +# +# 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. + +from neutron_lib import constants + + +VALID_VALUES = [None, constants.ACTIVE, constants.DOWN] + +# The alias of the extension. +ALIAS = 'data-plane-status' + +# Whether or not this extension is simply signaling behavior to the user +# or it actively modifies the attribute map. +IS_SHIM_EXTENSION = False + +# Whether the extension is marking the adoption of standardattr model for +# legacy resources, or introducing new standardattr attributes. False or +# None if the standardattr model is adopted since the introduction of +# resource extension. +# If this is True, the alias for the extension should be prefixed with +# 'standard-attr-'. +IS_STANDARD_ATTR_EXTENSION = False + +# The name of the extension. +NAME = 'Port data plane status extension' + +# The description of the extension. +DESCRIPTION = "Expose status of underlying data plane" + +# A timestamp of when the extension was introduced. +UPDATED_TIMESTAMP = "2017-01-24T10:00:00-00:00" + +# The name of the resource introduced or being extended. +RESOURCE_NAME = 'port' + +# The plural for the resource introduced or being extended. +COLLECTION_NAME = 'ports' + +# The specific resources and/or attributes for the extension (optional). +DATA_PLANE_STATUS = 'data_plane_status' + +# The resource attribute map for the extension. +RESOURCE_ATTRIBUTE_MAP = { + COLLECTION_NAME: { + DATA_PLANE_STATUS: {'allow_post': False, 'allow_put': True, + 'default': constants.ATTR_NOT_SPECIFIED, + 'validate': {'type:values': VALID_VALUES}, + 'is_visible': True, + 'enforce_policy': True, } + }, +} + +# The subresource attribute map for the extension. +SUB_RESOURCE_ATTRIBUTE_MAP = { +} + +# The action map. +ACTION_MAP = { +} + +# The list of required extensions. +REQUIRED_EXTENSIONS = [ +] + +# The list of optional extensions. +OPTIONAL_EXTENSIONS = [ +] diff --git a/neutron_lib/tests/unit/api/definitions/test_data_plane_status.py b/neutron_lib/tests/unit/api/definitions/test_data_plane_status.py new file mode 100644 index 000000000..6114d0ff9 --- /dev/null +++ b/neutron_lib/tests/unit/api/definitions/test_data_plane_status.py @@ -0,0 +1,22 @@ +# Copyright (c) 2017 NEC Corporation. All rights reserved. +# +# 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. + +from neutron_lib.api.definitions import data_plane_status as dps +from neutron_lib.tests.unit.api.definitions import base + + +class DataPlaneStatusDefinitionTestCase(base.DefinitionBaseTestCase): + extension_module = dps + extension_resources = (dps.COLLECTION_NAME,) + extension_attributes = (dps.DATA_PLANE_STATUS,) diff --git a/releasenotes/notes/data-plane-status-ext-c3452a01ef5007ce.yaml b/releasenotes/notes/data-plane-status-ext-c3452a01ef5007ce.yaml new file mode 100644 index 000000000..60a0beb5d --- /dev/null +++ b/releasenotes/notes/data-plane-status-ext-c3452a01ef5007ce.yaml @@ -0,0 +1,4 @@ +--- +features: + - API definition and reference documentation for the port data plane status + extension.