Add api-ref for tap service and tap flow

Change-Id: Ib1aa1a9cd2c42dbed7442010fb0d854ce59472d3

api-ref/source/v2/index.rst

@@ -112,3 +112,7 @@ Networking Agents
 Auto Allocated Topology
 #######################
 .. include:: auto-topology.inc
+#################
+Tap as a Service
+#################
+.. include:: taas.inc

api-ref/source/v2/parameters.yaml

@@ -490,6 +490,18 @@ description-query:
   in: query
   required: false
   type: string
+description_taf-query:
+  description: |
+    Filter the list result by the human-readable description of the resource.
+  in: query
+  required: false
+  type: string
+description_tas-query:
+  description: |
+    Filter the list result by the human-readable description of the resource.
+  in: query
+  required: false
+  type: string
 device_id-query:
   description: |
     Filter the port list result by the ID of the device that uses this port.
@@ -512,6 +524,12 @@ direction-query:
   in: query
   required: false
   type: string
+direction_taf-query:
+  description: |
+    Direction of the Tap flow. Possible options are: IN, OUT, BOTH
+  in: query
+  required: false
+  type: string
 dscp_mark-query:
   description: |
     Filter the list result by the DSCP mark value.
@@ -945,6 +963,12 @@ min_prefixlen-query:
   in: query
   required: false
   type: integer
+mirror_port_tas-query:
+  description: |
+    Port to which the Tap service is connected.
+  in: query
+  requried: true
+  type: string
 mtu-query:
   description: |
     Filter the network list result by the maximum transmission unit (MTU)
@@ -1141,6 +1165,13 @@ port_range_min-query:
   in: query
   required: false
   type: integer
+project-domain_taas:
+  description: |
+    Domain the project belongs to (name or ID).
+    This can be used in case collisions between project names exist.
+  in: query
+  requried: false
+  type: string
 project_id-query:
   description: |
     Filter the list result by the ID of the project that owns the resource.
@@ -1468,6 +1499,12 @@ sort_dir:
   in: query
   required: false
   type: string
+source_port_taf-query:
+  description: |
+    Source port to which the Tap Flow is connected.
+  in: query
+  requried: true
+  type: string
 state-query:
   description: |
     Filter the list result by the state of the availability zone, which is
@@ -1475,6 +1512,18 @@ state-query:
   in: query
   required: false
   type: string
+status_taf-query:
+  description: |
+    Human-readable description of the status for tap flow.
+  in: query
+  required: false
+  type: string
+status_tas-query:
+  description: |
+    Human-readable description of the status for tap service.
+  in: query
+  required: false
+  type: string
 subnet-dns_publish_fixed_ip-query:
   description: |
     Filter the subnet list result based on if ``dns_publish_fixed_ip`` is
@@ -1587,6 +1636,18 @@ subnetpool_is_default-query:
   in: query
   required: false
   type: boolean
+taf_id-query:
+  description: |
+    The ID of the Tap flow.
+  in: query
+  required: false
+  type: string
+taf_name-query:
+  description: |
+    The name of the Tap flow.
+  in: query
+  required: true
+  type: string
 tags-any-query:
   description: |
     A list of tags to filter the list result by.
@@ -1603,6 +1664,12 @@ tags-query:
   in: query
   required: false
   type: string
+tap_service_id-query:
+  description: |
+    Tap Service to which the Tap Flow belongs.
+  in: query
+  required: false
+  type: string
 target_tenant-query:
   description: |
     Filter the RBAC policy list result by the ID of the tenant to which the
@@ -1610,6 +1677,18 @@ target_tenant-query:
   in: query
   required: false
   type: string
+tas_id-query:
+  description: |
+    The ID of the Tap Service.
+  in: query
+  required: false
+  type: string
+tas_name-query:
+  description: |
+    The name of the Tap Service.
+  in: query
+  required: true
+  type: string
 topic-query:
   description: |
     Filter the list result by the name of AMQP topic the agent is listening on
@@ -1651,6 +1730,12 @@ verbose:
   in: query
   required: false
   type: boolean
+vlan-filter_taf-query:
+  description: |
+    VLAN Ids to be mirrored in the form of range string.
+  in: query
+  required: false
+  type: string
 vlan_transparent-query:
   description: |
     Filter the network list by the VLAN transparency mode of the network,
@@ -2730,6 +2815,18 @@ description_resource:
   in: body
   required: true
   type: string
+description_taf:
+  description: |
+    The description for this Tap Flow.
+  in: body
+  required: true
+  type: string
+description_tas:
+  description: |
+    The description for this Tap Service.
+  in: body
+  required: true
+  type: string
 destination_firewall_group_id-body-optional:
   description: |
     The ID of the remote destination firewall group.
@@ -2829,6 +2926,12 @@ direction:
   in: body
   required: true
   type: string
+direction_taf:
+  description: |
+    Direction of the Tap flow. Possible options are: IN, OUT, BOTH
+  in: body
+  required: true
+  type: string
 dns_assignment:
   description: |
     Data assigned to a port by the Networking internal DNS including the
@@ -4645,6 +4748,12 @@ minimum_packet_rate_rules:
   in: body
   required: true
   type: array
+mirror_port_tas:
+  description: |
+    Port to which the Tap service is connected.
+  in: body
+  required: true
+  type: string
 mtu:
   description: |
     The maximum transmission unit (MTU) value to
@@ -6403,6 +6512,12 @@ source_port-response:
   in: body
   required: false
   type: string
+source_port_taf:
+  description: |
+    Source port to which the Tap Flow is connected.
+  in: body
+  required: true
+  type: string
 started_at:
   description: |
     Time at which the agent was started.
@@ -6428,6 +6543,18 @@ status_description:
   in: body
   required: true
   type: string
+status_taf:
+  description: |
+    Human-readable description of the status for tap flow.
+  in: body
+  required: true
+  type: string
+status_tas:
+  description: |
+    Human-readable description of the status for tap service.
+  in: body
+  required: true
+  type: string
 sub_ports:
   description: |
     A list of ports associated with the trunk.
@@ -6698,18 +6825,48 @@ subnets-obj:
   in: body
   required: true
   type: array
+taf_id:
+  description: |
+    The id for the Tap Flow.
+  in: body
+  required: true
+  type: string
+taf_name:
+  description: |
+    The name for the Tap Flow.
+  in: body
+  required: true
+  type: string
 tags:
   description: |
     The list of tags on the resource.
   in: body
   required: true
   type: array
+tap_service_id:
+  description: |
+    Tap Service to which the Tap Flow belongs.
+  in: body
+  required: true
+  type: string
 target_tenant:
   description: |
     The ID of the tenant to which the RBAC policy will be enforced.
   in: body
   required: true
   type: string
+tas_id:
+  description: |
+    Tha id for the Tap Service.
+  in: body
+  required: true
+  type: string
+tas_name:
+  description: |
+    Tha name for the Tap Flow.
+  in: body
+  required: true
+  type: string
 topic:
   description: |
     The name of AMQP topic the agent is listening on such as
@@ -6830,6 +6987,12 @@ versions:
   in: body
   required: true
   type: array
+vlan-filter_taf:
+  description: |
+    VLAN Ids to be mirrored in the form of range string.
+  in: body
+  required: true
+  type: boolean
 vlan_transparent:
   description: |
     Indicates the VLAN transparency mode of the network, which is

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

@@ -0,0 +1,8 @@
+{
+    "tap_flow": {
+        "name": "tf1",
+        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
+        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
+        "direction": "BOTH"
+    }
+}

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

@@ -0,0 +1,14 @@
+{
+    "tap_flow": {
+        "id": "137086d8-a77b-4bbc-825f-9c2f7b9bfa7b",
+        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
+        "name": "tf1",
+        "description": "",
+        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
+        "direction": "BOTH",
+        "status": "DOWN",
+        "vlan_filter": null,
+        "project_id": "dad19b09dba44e589c022000d580e9d5"
+    }
+}

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

@@ -0,0 +1,13 @@
+{
+    "tap_flows": [
+        {
+            "ID": "4082b3f6-387f-4d1e-b67e-f47f0dcd2926",
+            "Tenant": "dad19b09dba44e589c022000d580e9d5",
+            "Name": "tf1",
+            "Status": "ACTIVE",
+            "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
+            "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
+            "Direction": "BOTH"
+        }
+    ]
+}

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

@@ -0,0 +1,14 @@
+{
+    "tap_flow": {
+        "id": "137086d8-a77b-4bbc-825f-9c2f7b9bfa7b",
+        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
+        "name": "tf1",
+        "description": "test tap flow",
+        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
+        "direction": "BOTH",
+        "status": "DOWN",
+        "vlan_filter": null,
+        "project_id": "dad19b09dba44e589c022000d580e9d5"
+    }
+}

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

@@ -0,0 +1,5 @@
+{
+    "tap_flow": {
+        "description": "test tap flow"
+    }
+}

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

@@ -0,0 +1,14 @@
+{
+    "tap_flow": {
+        "id": "137086d8-a77b-4bbc-825f-9c2f7b9bfa7b",
+        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
+        "name": "tf1",
+        "description": "test tap flow",
+        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
+        "direction": "BOTH",
+        "status": "DOWN",
+        "vlan_filter": null,
+        "project_id": "dad19b09dba44e589c022000d580e9d5"
+    }
+}

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

@@ -0,0 +1,6 @@
+{
+    "tap_service": {
+        "name": "ts1",
+        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01"
+    }
+}

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

@@ -0,0 +1,11 @@
+{
+    "tap_service": {
+        "id": "2fec9339-f565-46d0-947b-1d98c2a406aa",
+        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+        "name": "tap_service-1",
+        "description": "tap service",
+        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
+        "status": "DOWN",
+        "project_id": "dad19b09dba44e589c022000d580e9d5"
+    }
+}

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

@@ -0,0 +1,11 @@
+{
+    "tap_services": [
+        {
+            "id": "257bcb47-5134-4ee9-b5cc-762d99ddae0b",
+            "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+            "name": "tap_service-1",
+            "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
+            "status": "ACTIVE"
+        }
+    ]
+}

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

@@ -0,0 +1,11 @@
+{
+    "tap_service": {
+        "id": "1b059120-078b-4f25-bb16-e14d69706a9a",
+        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+        "name": "ts1",
+        "description": "",
+        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
+        "status": "ACTIVE",
+        "project_id": "dad19b09dba44e589c022000d580e9d5"
+    }
+}

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

@@ -0,0 +1,5 @@
+{
+    "tap_service": {
+        "description": "test tap service"
+    }
+}

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

@@ -0,0 +1,11 @@
+{
+    "tap_service": {
+        "id": "2fec9339-f565-46d0-947b-1d98c2a406aa",
+        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
+        "name": "ts1",
+        "description": "test tas",
+        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
+        "status": "ACTIVE",
+        "project_id": "dad19b09dba44e589c022000d580e9d5"
+    }
+}

api-ref/source/v2/taas.inc

@@ -0,0 +1,430 @@
+.. -*- rst -*-
+
+================
+Tap As A Service
+================
+
+TaaS plugin provides a mechanism to mirror certain traffic
+(for example tagged with specific VLANs) from a source VM to any traffic analyzer VM.
+When packet will be forwarded, the original value of source and target ip/ports
+information will not be altered and the system administrator will be able to run,
+for ex. ``tcpdump``, on the target VM to trace these packets.
+
+TaaS plugin mainly consists of ``tap service`` and ``tap flow``.
+
+VLAN filter
+===========
+
+The ``VLAN filtering`` for Neutron Tap as a Service allows to filter
+traffic comming from ``tap-flows`` by VLAN id in case of mirroring SRIOV
+ports.
+
+Tap Service
+===========
+
+TapService represents the port to which the mirrored traffic is delivered.
+
+List Tap Services
+=================
+
+.. rest_method:: GET /v2.0/taas/tap_services
+
+List tap services 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: tas_id
+   - tenant_id: project_id
+   - port: mirror_port_tas
+   - status: status_tas
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tas-list-response.json
+   :language: javascript
+
+Create Tap Service
+==================
+
+.. rest_method:: POST /v2.0/taas/tap_services
+
+Create a Tap Service by passing the following JSON-encoded data.
+``name``, ``monitoring port`` as mandatory parameters and
+``description`` as optional parameter.
+
+Normal response codes: 201
+
+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-query
+   - name: tas_name-query
+   - port: mirror_port_tas-query
+   - description: description_tas-query
+
+Request Example
+---------------
+
+.. literalinclude:: samples/taas/tas-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tas_id
+   - tenant_id: project_id
+   - name: tas_name
+   - port: mirror_port_tas
+   - status: status_tas
+   - description: description_tas
+   - project_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tas-create-response.json
+   :language: javascript
+
+Update Tap Service
+==================
+
+.. rest_method:: PUT /v2.0/taas/tap_services/{tap_service_id/name}
+
+Update Tap Service by passing tap service ``name`` or ``id`` as JSON-encoded data.
+Name or description or both can only be updated.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: tas_name-query
+   - description: description_tas-query
+
+Request Example
+---------------
+
+.. literalinclude:: samples/taas/tas-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tas_id
+   - name: tas_name
+   - port: mirror_port_tas
+   - status: status_tas
+   - description: description_tas
+   - project_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tas-update-response.json
+   :language: javascript
+
+Delete Tap Service
+==================
+
+.. rest_method:: DELETE /v2.0/taas/tap_services/{tap_service_id/name}
+
+Delete Tap Service by passing tap service ``name`` or ``id`` as JSON-encoded data.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 404, 412
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: tas_name-query
+   - id: tas_id-query
+
+Response Parameters
+-------------------
+
+There is no body content for the response of a successful DELETE request.
+
+Show Tap Service
+================
+
+.. rest_method:: GET /v2.0/taas/tap_services/{tap_service_id/name}
+
+Show details for a tap service by passing tap service ``name`` or ``id`` as JSON-encoded data.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - project: project_id-query
+   - project-domain: project-domain_taas
+   - name: tas_name-query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: tas_id
+   - name: tas_name
+   - port: mirror_port_tas
+   - status: status_tas
+   - description: description_tas
+   - project_id: project_id
+   - tenant_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/tas-show-response.json
+   :language: javascript
+
+
+Tap Flow
+========
+
+TapFlow represents the port from which the traffic needs to be mirrored.
+It can be a port associated with VM on another cloud network.
+
+List Tap Flow
+=============
+
+.. rest_method:: GET /v2.0/taas/tap_flows
+
+List tap flow that belong to a given tenant.
+
+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: taf_id
+   - port: source_port_taf
+   - status: status_tas
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/taf-list-response.json
+   :language: javascript
+
+Create Tap Flow
+===============
+
+.. rest_method:: POST /v2.0/taas/tap_flows
+
+Create a Tap Flow by passing the following JSON-encoded data.
+``name``, ``source port``, ``direction`` as ``IN/OUT/BOTH``
+``tap_service`` as mandatory parameters and
+``description`` as optional parameter.
+
+Normal response codes: 201
+
+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-query
+   - name: taf_name-query
+   - port: source_port_taf-query
+   - tap_service: tap_service_id-query
+   - vlan_filter: vlan-filter_taf-query
+   - direction: direction_taf-query
+   - description: description_taf-query
+
+Request Example
+---------------
+
+.. literalinclude:: samples/taas/taf-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: taf_id
+   - name: taf_name
+   - port: source_port_taf
+   - status: status_taf
+   - tap_service: tap_service_id
+   - direction: description_taf
+   - project_id: project_id
+   - tenant_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/taf-create-response.json
+   :language: javascript
+
+Update Tap Flow
+===============
+
+.. rest_method:: PUT /v2.0/taas/tap_flows/{taf_service_id/name}
+
+Update Tap Flow by passing tap flow ``name`` or ``id`` as JSON-encoded data.
+Name or description or both can only be updated.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: taf_name-query
+   - description: description_taf-query
+
+Request Example
+---------------
+
+.. literalinclude:: samples/taas/taf-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: taf_id
+   - name: taf_name
+   - port: source_port_taf
+   - status: status_tas
+   - tap_service: tap_service_id
+   - direction: description_taf
+   - project_id: project_id
+   - tenant_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/taf-update-response.json
+   :language: javascript
+
+Delete Tap Flow
+===============
+
+.. rest_method:: DELETE /v2.0/taas/tap_flows/{tap_service_id/name}
+
+Delete Tap Flow by passing tap flow ``name`` or ``id`` as JSON-encoded data.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 404, 412
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: taf_id-query
+   - name: taf_name-query
+
+Response Parameters
+-------------------
+
+On successful ``DELETE`` request ``Tap flow {tap_flow_id} deleted.``
+message will be displayed.
+
+Show Tap Flow
+=============
+
+.. rest_method:: GET /v2.0/taas/tap_flows/{tap_flows_id/name}
+
+Show details for a tap flow by passing tap flow ``name`` or ``id`` as JSON-encoded data.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - project: project_id-query
+   - project-domain: project-domain_taas
+   - tenant_id: project_id-query
+   - id: taf_id-query
+   - name: taf_name-query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: taf_id
+   - name: taf_name
+   - port: source_port_taf
+   - status: status_taf
+   - tap_service: tap_service_id
+   - direction: description_taf
+   - project_id: project_id
+   - tenant_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/taas/taf-show-response.json
+   :language: javascript