Tap mirror API def and API ref

Change-Id: Ifa1bf6abbf5d25769820b545d8d3bab195b146d3
Related-Bug: #2015471

api-ref/source/v2/index.rst

@@ -121,6 +121,7 @@ Auto Allocated Topology
 Tap as a Service
 #################
 .. include:: taas.inc
+.. include:: tap_mirrors.inc
 ##################
 Networking SFC API
 ##################

api-ref/source/v2/parameters.yaml

@@ -1751,6 +1751,12 @@ tags-query:
   in: query
   required: false
   type: string
+tap_mirror_id-query:
+  description: |
+    The id of the Tap Mirror.
+  in: query
+  required: true
+  type: string
 tap_service_id-query:
   description: |
     Tap Service to which the Tap Flow belongs.
@@ -2915,6 +2921,13 @@ direction_taf:
   in: body
   required: true
   type: string
+directions_tap_mirror:
+  description: |
+    A dictionary of ``direction`` and ``tunnel_id``.
+    Direction can be ``IN`` and ``OUT``.
+  in: body
+  required: true
+  type: object
 dns_assignment:
   description: |
     Data assigned to a port by the Networking internal DNS including the
@@ -4810,6 +4823,12 @@ mirror_port_tas:
   in: body
   required: true
   type: string
+mirror_type:
+  description: |
+    The type of the mirroring, it can be ``gre`` or ``erspanv1``.
+  in: body
+  required: true
+  type: string
 mtu:
   description: |
     The maximum transmission unit (MTU) value to
@@ -6058,6 +6077,13 @@ remote_ip_prefix-request:
   in: body
   required: false
   type: string
+remote_ip_tap_mirror:
+  description: |
+    The remote IP of the Tap Mirror, this will be the remote end of the
+    GRE or ERSPAN v1 tunnel.
+  in: body
+  required: true
+  type: string
 resource:
   description: |
     The resource type of the availability zone. The supported resource types
@@ -7144,6 +7170,26 @@ tags:
   in: body
   required: true
   type: array
+tap_mirror_id:
+  description: |
+    The ID of the Tap Mirror.
+  in: body
+  required: true
+  type: string
+tap_mirror_name:
+  description: |
+    The name of the Tap Mirror
+  in: body
+  required: true
+  type: string
+tap_mirror_port_id:
+  description: |
+    The Port ID of the Tap Mirror, this will be the source of the mirrored
+    traffic, and this traffic will be tunneled into the GRE or ERSPAN v1
+    tunnel. The tunnel itself is not starting from this port!
+  in: body
+  required: true
+  type: string
 tap_service_id:
   description: |
     Tap Service to which the Tap Flow belongs.

api-ref/source/v2/samples/taas/tap_mirror-create-request.json

@@ -0,0 +1,10 @@
+{
+    "tap_mirror": {
+        "name": "mirror2",
+        "description": "Two direction mirror",
+        "port_id":"c63e4f48-da76-466c-a6f1-f4e4a4902c6a",
+        "directions": {"IN": 99, "OUT": 100},
+        "remote_ip":"100.109.0.142",
+        "mirror_type":"erspanv1"
+    }
+}

api-ref/source/v2/samples/taas/tap_mirror-create-response.json

@@ -0,0 +1,13 @@
+{
+    "tap_mirror": {
+        "id": "6ffe758f-d426-4718-9e33-71c542634d2b",
+        "project_id": "57425788f1a148059926c124a6ffabe6",
+        "name": "mirror2",
+        "description": "Two direction mirror",
+        "port_id": "c63e4f48-da76-466c-a6f1-f4e4a4902c6a",
+        "directions": {"IN": 99, "OUT": 100},
+        "remote_ip": "100.109.0.142",
+        "mirror_type": "erspanv1",
+        "tenant_id": "57425788f1a148059926c124a6ffabe6"
+    }
+}

api-ref/source/v2/samples/taas/tap_mirror-list-response.json

@@ -0,0 +1,17 @@
+{
+    "tap_mirrors": [
+        {
+            "description": "My fancy tap mirror with direction IN and id 99",
+            "directions": {
+                "IN": 99
+            },
+            "id": "207e4809-5358-4592-891b-3312bed32c47",
+            "mirror_type": "gre",
+            "name": "my_tap_mirror",
+            "port_id": "81bc638f-e991-4306-ae5e-df8492890b39",
+            "project_id": "57425788f1a148059926c124a6ffabe6",
+            "remote_ip": "100.109.0.142",
+            "tenant_id": "57425788f1a148059926c124a6ffabe6"
+        }
+    ]
+}

api-ref/source/v2/samples/taas/tap_mirror-show-response.json

@@ -0,0 +1,15 @@
+{
+   "tap_mirror" : {
+      "description" : "My fancy tap mirror with direction IN and id 99",
+      "directions" : {
+         "IN" : 99
+      },
+      "id" : "0f077b67-e85b-4138-bc64-5d705b0a06ef",
+      "mirror_type" : "gre",
+      "name" : "my_tap_mirror",
+      "port_id" : "81bc638f-e991-4306-ae5e-df8492890b39",
+      "project_id" : "57425788f1a148059926c124a6ffabe6",
+      "remote_ip" : "100.109.0.142",
+      "tenant_id" : "57425788f1a148059926c124a6ffabe6"
+   }
+}

api-ref/source/v2/samples/taas/tap_mirror-update-request.json

@@ -0,0 +1,6 @@
+{
+    "tap_mirror": {
+        "name": "my_tap_mirror",
+        "description":"My fancy tap mirror with direction IN and id 99"
+    }
+}

api-ref/source/v2/samples/taas/tap_mirror-update-response.json

@@ -0,0 +1,13 @@
+{
+    "tap_mirror": {
+        "id": "207e4809-5358-4592-891b-3312bed32c47",
+        "project_id": "57425788f1a148059926c124a6ffabe6",
+        "name": "my_tap_mirror",
+        "description": "My fancy tap mirror with direction IN and id 99",
+        "port_id": "81bc638f-e991-4306-ae5e-df8492890b39",
+        "directions": {"IN": 99},
+        "remote_ip": "100.109.0.142",
+        "mirror_type": "gre",
+        "tenant_id": "57425788f1a148059926c124a6ffabe6"
+    }
+}

api-ref/source/v2/tap_mirrors.inc

@@ -0,0 +1,208 @@
+.. -*- rst -*-
+
+===========
+Tap Mirrors
+===========
+
+Tap Mirrors provide a way to mirror traffic from a Neutron port to an external
+IP in a GRE or ERSPAN v1 tunnel.
+
+List Tap Mirrors
+=================
+
+.. rest_method:: GET /v2.0/taas/tap_mirrors
+
+List tap mirrors that belong to a given project.
+
+The list might be empty.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - project: project_id-query
+   - project-domain: project-domain_taas
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tap_mirror_id
+   - name: tap_mirror_name
+   - description: description
+   - tenant_id: project_id
+   - port_id: tap_mirror_port_id
+   - mirror_type: mirror_type
+   - remote_ip: remote_ip_tap_mirror
+   - directions: directions_tap_mirror
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tap_mirror-list-response.json
+   :language: javascript
+
+Create Tap Mirror
+=================
+
+.. rest_method:: POST /v2.0/taas/tap_mirrors
+
+Creates a Tap Mirror.
+
+Error response codes: 401, 403, 404, 409
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - project: project_id-query
+   - project-domain: project-domain_taas
+   - tenant_id: project_id
+   - name: tap_mirror_name
+   - port_id: tap_mirror_port_id
+   - mirror_type: mirror_type
+   - remote_ip: remote_ip_tap_mirror
+   - directions: directions_tap_mirror
+   - description: description
+
+Request Example
+---------------
+
+.. literalinclude:: samples/taas/tap_mirror-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tap_mirror_id
+   - name: tap_mirror_name
+   - description: description
+   - tenant_id: project_id
+   - port_id: tap_mirror_port_id
+   - mirror_type: mirror_type
+   - remote_ip: remote_ip_tap_mirror
+   - directions: directions_tap_mirror
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tap_mirror-create-response.json
+   :language: javascript
+
+Update Tap Mirror
+=================
+
+.. rest_method:: PUT /v2.0/taas/tap_mirrors/{tap_mirror_id}
+
+Updates Tap Mirror.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - tap_mirror_id: tap_mirror_id-query
+   - description: description
+   - name: tap_mirror_name
+
+Request Example
+---------------
+
+.. literalinclude:: samples/taas/tap_mirror-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tap_mirror_id
+   - name: tap_mirror_name
+   - description: description
+   - tenant_id: project_id
+   - port_id: tap_mirror_port_id
+   - mirror_type: mirror_type
+   - remote_ip: remote_ip_tap_mirror
+   - directions: directions_tap_mirror
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tap_mirror-update-response.json
+   :language: javascript
+
+Delete Tap Mirror
+=================
+
+.. rest_method:: DELETE /v2.0/taas/tap_mirrors/{tap_mirror_id}
+
+Deleted a Tap Mirror.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 404, 412
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - tap_mirror_id: tap_mirror_id-query
+
+Response Parameters
+-------------------
+
+There is no body content for the response of a successful DELETE request.
+
+Show Tap Mirror
+===============
+
+.. rest_method:: GET /v2.0/taas/tap_mirrors/{tap_mirror_id}
+
+Shows details for a tap mirror.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - project: project_id-query
+   - project-domain: project-domain_taas
+   - tap_mirror_id: tap_mirror_id-query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tap_mirror_id
+   - name: tap_mirror_name
+   - description: description
+   - tenant_id: project_id
+   - port_id: tap_mirror_port_id
+   - mirror_type: mirror_type
+   - remote_ip: remote_ip_tap_mirror
+   - directions: directions_tap_mirror
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tap_mirror-show-response.json
+   :language: javascript

neutron_lib/api/definitions/__init__.py

@@ -153,6 +153,7 @@ from neutron_lib.api.definitions import subnetpool
 from neutron_lib.api.definitions import subnetpool_prefix_ops
 from neutron_lib.api.definitions import taas
 from neutron_lib.api.definitions import tag_ports_during_bulk_creation
+from neutron_lib.api.definitions import tap_mirror
 from neutron_lib.api.definitions import trunk
 from neutron_lib.api.definitions import trunk_details
 from neutron_lib.api.definitions import uplink_status_propagation
@@ -307,6 +308,7 @@ _ALL_API_DEFINITIONS = {
     subnetpool_prefix_ops,
     taas,
     tag_ports_during_bulk_creation,
+    tap_mirror,
     trunk,
     trunk_details,
     uplink_status_propagation,

neutron_lib/api/definitions/base.py

@@ -197,6 +197,7 @@ KNOWN_EXTENSIONS = (
 
     # https://opendev.org/openstack/tap-as-a-service
     'taas',
+    'tap_mirrors',
     'taas-vlan-filter',
 )
 

neutron_lib/api/definitions/tap_mirror.py

@@ -0,0 +1,76 @@
+# 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 taas
+from neutron_lib.db import constants as db_const
+
+
+ALIAS = 'tap-mirror'
+IS_SHIM_EXTENSION = False
+IS_STANDARD_ATTR_EXTENSION = False
+NAME = "Tap as a Service GRE or ERSPAN mirror"
+DESCRIPTION = "Neutron Tap as a Service extension for GRE or ERSPAN mirroring."
+UPDATED_TIMESTAMP = "2023-05-05T11:45:00-00:00"
+RESOURCE_NAME = 'tap_mirror'
+COLLECTION_NAME = 'tap_mirrors'
+
+mirror_types_list = ['erspanv1', 'gre']
+DIRECTION_SPEC = {
+    'type:dict': {
+        'IN': {'type:integer': None, 'default': None, 'required': False},
+        'OUT': {'type:integer': None, 'default': None, 'required': False}
+    }
+}
+
+RESOURCE_ATTRIBUTE_MAP = {
+    COLLECTION_NAME: {
+        'id': {
+            'allow_post': False, 'allow_put': False,
+            'validate': {'type:uuid': None}, 'is_visible': True,
+            'primary_key': True},
+        'project_id': {
+            'allow_post': True, 'allow_put': False,
+            'validate': {'type:string': db_const.PROJECT_ID_FIELD_SIZE},
+            'required_by_policy': True, 'is_filter': True,
+            'is_sort_key': True, 'is_visible': True},
+        'name': {
+            'allow_post': True, 'allow_put': True,
+            'validate': {'type:string': None},
+            'is_visible': True, 'default': ''},
+        'description': {
+            'allow_post': True, 'allow_put': True,
+            'validate': {'type:string': None},
+            'is_visible': True, 'default': ''},
+        'port_id': {
+            'allow_post': True, 'allow_put': False,
+            'validate': {'type:uuid': None},
+            'enforce_policy': True, 'is_visible': True},
+        'directions': {
+            'allow_post': True, 'allow_put': False,
+            'validate': DIRECTION_SPEC,
+            'is_visible': True},
+        'remote_ip': {
+            'allow_post': True, 'allow_put': False,
+            'validate': {'type:ip_address': None},
+            'is_visible': True},
+        'mirror_type': {
+            'allow_post': True, 'allow_put': False,
+            'validate': {'type:values': mirror_types_list},
+            'is_visible': True},
+    }
+}
+
+SUB_RESOURCE_ATTRIBUTE_MAP = None
+ACTION_MAP = {}
+ACTION_STATUS = {}
+REQUIRED_EXTENSIONS = [taas.ALIAS]
+OPTIONAL_EXTENSIONS = []

neutron_lib/tests/unit/api/definitions/test_tap_mirror.py

@@ -0,0 +1,23 @@
+# 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 tap_mirror
+from neutron_lib.tests.unit.api.definitions import base
+
+
+class TapMirrorDefinitionTestCase(base.DefinitionBaseTestCase):
+    extension_module = tap_mirror
+    extension_resources = (tap_mirror.COLLECTION_NAME, )
+    extension_attributes = ('port_id', 'remote_ip', 'directions',
+                            'mirror_type')

releasenotes/notes/tap-mirrors-fe2b6770021933c2.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    New API definition ``tap-mirror``, this new extension for tap-as-a-service
+    allows admins to mirror traffic from a Neutron port to a remote IP
+    address with GRE or ERSPAN v1 tunnels.