62b8bb7213
Add possibility to tap-as-a-service to use openstack commands instead of deprecated neutron commands. Closes-Bug: #1874701 Change-Id: I339f42a63789a946011700902724a58647c80b9d
320 lines
9.7 KiB
ReStructuredText
320 lines
9.7 KiB
ReStructuredText
==============================
|
|
Tap as a Service API REFERENCE
|
|
==============================
|
|
|
|
This documents is an API REFERENCE for Tap-as-a-Service Neutron extension.
|
|
|
|
The documents is organized into the following sections:
|
|
* TaaS Resources
|
|
* API Reference
|
|
* TaaS CLI Reference
|
|
* Workflow
|
|
|
|
TaaS Resources
|
|
==============
|
|
|
|
TaaS consists of two resources, TapService and TapFlow.
|
|
|
|
TapService
|
|
----------
|
|
|
|
TapService Represents the port on which the mirrored traffic is delivered.
|
|
Any service (VM) that uses the mirrored data is attached to the port.
|
|
|
|
.. code-block:: python
|
|
|
|
'tap_services': {
|
|
'id': {'allow_post': False, 'allow_put': False,
|
|
'validate': {'type:uuid': None}, 'is_visible': True,
|
|
'primary_key': True},
|
|
'tenant_id': {'allow_post': True, 'allow_put': False,
|
|
'validate': {'type:string': None},
|
|
'required_by_policy': 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},
|
|
'is_visible': True},
|
|
}
|
|
|
|
TapFlow
|
|
-------
|
|
|
|
TapFlow Represents the port from which the traffic needs to be mirrored.
|
|
|
|
.. code-block:: python
|
|
|
|
'tap_flows': {
|
|
'id': {'allow_post': False, 'allow_put': False,
|
|
'validate': {'type:uuid': None}, 'is_visible': True,
|
|
'primary_key': True},
|
|
'tenant_id': {'allow_post': True, 'allow_put': False,
|
|
'validate': {'type:string': None},
|
|
'required_by_policy': 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': ''},
|
|
'tap_service_id': {'allow_post': True, 'allow_put': False,
|
|
'validate': {'type:uuid': None},
|
|
'required_by_policy': True, 'is_visible': True},
|
|
'source_port': {'allow_post': True, 'allow_put': False,
|
|
'validate': {'type:uuid': None},
|
|
'required_by_policy': True, 'is_visible': True},
|
|
'direction': {'allow_post': True, 'allow_put': False,
|
|
'validate': {'type:values': direction_enum},
|
|
'is_visible': True},
|
|
'vlan_filter': {'allow_post': True, 'allow_put': False,
|
|
'validate': {'type:regex_or_none': RANGE_REGEX},
|
|
'is_visible': True, 'default': None}
|
|
}
|
|
|
|
direction_enum = ['IN', 'OUT', 'BOTH']
|
|
|
|
|
|
Multiple TapFlow instances can be associated with a single TapService
|
|
instance.
|
|
|
|
API REFERENCE
|
|
=============
|
|
|
|
Below is the list of REST APIs that can be used to interact with TaaS Neutron
|
|
extension
|
|
|
|
1. Create TapService
|
|
|
|
\
|
|
|
|
**POST /v2.0/taas/tap_services**
|
|
|
|
\
|
|
|
|
Json Request:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
"tap_service": {
|
|
"description": "Test_Tap",
|
|
"name": "Test",
|
|
"port_id": "c9beb5a1-21f5-4225-9eaf-02ddccdd50a9",
|
|
"tenant_id": "97e1586d580745d7b311406697aaf097"
|
|
}
|
|
}
|
|
|
|
\
|
|
|
|
Json Response:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
"tap_service": {
|
|
"description": "Test_Tap",
|
|
"id": "c352f537-ad49-48eb-ab05-1c6b8cb900ff",
|
|
"name": "Test",
|
|
"port_id": "c9beb5a1-21f5-4225-9eaf-02ddccdd50a9",
|
|
"tenant_id": "97e1586d580745d7b311406697aaf097"
|
|
}
|
|
}
|
|
|
|
2. List TapServices
|
|
|
|
\
|
|
|
|
**GET /v2.0/taas/tap_services/{tap_service_uuid}**
|
|
|
|
\
|
|
|
|
Json Response:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
"tap_services": [
|
|
{
|
|
"description": "Test_Tap",
|
|
"id": "c352f537-ad49-48eb-ab05-1c6b8cb900ff",
|
|
"name": "Test",
|
|
"port_id": "c9beb5a1-21f5-4225-9eaf-02ddccdd50a9",
|
|
"tenant_id": "97e1586d580745d7b311406697aaf097"
|
|
}
|
|
]
|
|
}
|
|
|
|
3. Delete TapService
|
|
|
|
\
|
|
|
|
**DELETE /v2.0/taas/tap_services/{tap_service_uuid}**
|
|
|
|
\
|
|
|
|
4. Create TapFlow
|
|
|
|
\
|
|
|
|
**POST /v2.0/taas/tap_flows**
|
|
|
|
\
|
|
|
|
Json Request:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
"tap_flow": {
|
|
"description": "Test_flow1",
|
|
"direction": "BOTH",
|
|
"name": "flow1",
|
|
"source_port": "775a58bb-e2c6-4529-a918-2f019169b5b1",
|
|
"tap_service_id": "69bd12b2-0e13-45ec-9045-b674fd9f0468",
|
|
"tenant_id": "97e1586d580745d7b311406697aaf097",
|
|
"vlan_filter": "9,18-27,36,45,54-63"
|
|
}
|
|
}
|
|
|
|
\
|
|
|
|
Json Response:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
"tap_flow": {
|
|
"description": "Test_flow1",
|
|
"direction": "BOTH",
|
|
"id": "cc47f881-345f-4e62-ad24-bea79eb28304",
|
|
"name": "flow1",
|
|
"source_port": "775a58bb-e2c6-4529-a918-2f019169b5b1",
|
|
"tap_service_id": "69bd12b2-0e13-45ec-9045-b674fd9f0468",
|
|
"tenant_id": "97e1586d580745d7b311406697aaf097",
|
|
"vlan_filter": "9,18-27,36,45,54-63"
|
|
}
|
|
}
|
|
|
|
5. List TapFlows
|
|
|
|
\
|
|
|
|
**GET /v2.0/taas/tap_flows/{tap_flow_uuid}**
|
|
|
|
\
|
|
|
|
Json Response:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
"tap_flows": [
|
|
{
|
|
"description": "Test_flow1",
|
|
"direction": "BOTH",
|
|
"id": "cc47f881-345f-4e62-ad24-bea79eb28304",
|
|
"name": "flow1",
|
|
"source_port": "775a58bb-e2c6-4529-a918-2f019169b5b1",
|
|
"tap_service_id": "c352f537-ad49-48eb-ab05-1c6b8cb900ff",
|
|
"tenant_id": "97e1586d580745d7b311406697aaf097",
|
|
"vlan_filter": "9,18-27,36,45,54-63"
|
|
}
|
|
]
|
|
}
|
|
|
|
6. Delete TapFlow
|
|
|
|
\
|
|
|
|
**DELETE /v2.0/taas/tap_flows/{tap_flow_uuid}**
|
|
|
|
\
|
|
|
|
TaaS CLI Reference
|
|
==================
|
|
|
|
Openstack CLI
|
|
-------------
|
|
|
|
OpenStackClient provides
|
|
`the basic network commands <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__
|
|
and tap-as-a-service has an extension for taas related commands.
|
|
|
|
* Create tap service: **openstack tap service create** --name <name of the tap service> --port <name or ID of the port on which the traffic is delivered>
|
|
|
|
* List tap services: **openstack tap service list**
|
|
|
|
* Show tap service: **openstack tap service show** <tap service id/tap service name>
|
|
|
|
* Delete tap service: **openstack tap service delete** <tap service id/tap service name>
|
|
|
|
* Update tap service: **openstack tap service update** <tap service id/tap service name> --name <new name of the tap service> --description <new description of the tap service>
|
|
|
|
* Create tap flow: **openstack tap flow create** --name <name of the tap flow> --port <name or ID of the Source port to which the Tap Flow is connected> --tap-service <name or ID of the tap service> --direction <Direction of the Tap flow. Possible options are: IN, OUT, BOTH> --vlan-filter <LAN Ids to be mirrored in the form of range string>
|
|
|
|
* List tap flows **openstack tap flow list**
|
|
|
|
* Show tap flow **openstack tap flow show** <tap flow id/tap flow name>
|
|
|
|
* Delete tap flow **openstack tap flow delete** <tap flow id/tap flow name>
|
|
|
|
* Update tap flow **openstack tap flow update** <tap flow id/tap flow name> --name <new name of the tap flow> --description <new description of the tap flow>
|
|
|
|
Neutron CLI
|
|
-----------
|
|
|
|
.. warning::
|
|
|
|
neutron CLI is now deprecated, and will be removed in the future.
|
|
Use openstack CLI instead.
|
|
|
|
The TaaS commands can be executed using TaaS CLI, which is integrated with neutron.
|
|
It can be used to send REST request and interact with the TaaS
|
|
extension. Given below are the detail of the CLIs:
|
|
|
|
- **neutron tap-service-create**: Creates a Tap service.
|
|
- **neutron tap-service-list**: Lists all the Tap services.
|
|
- **neutron tap-service-show**: Show the details for a Tap service.
|
|
- **neutron tap-service-update**: Update the information for a Tap service.
|
|
- **neutron tap-service-delete**: Delete an existing Tap service.
|
|
- **neutron tap-flow-create**: Creates a Tap flow.
|
|
- **neutron tap-flow-list**: Lists all the Tap flows.
|
|
- **neutron tap-flow-show**: Show the details for a Tap flow.
|
|
- **neutron tap-flow-update**: Update the information for a Tap flow.
|
|
- **neutron tap-flow-delete**: Delete an existing Tap flow.
|
|
|
|
For usage type **--help** after any of the above commands
|
|
in the terminal after TaaS has been installed.
|
|
|
|
Workflow
|
|
=========
|
|
|
|
In this section we describe a simple sequence of steps to use TaaS.
|
|
|
|
Workflow Sequence
|
|
------------------
|
|
|
|
1. Create a Neutron port with 'port_security_enabled' set to 'false'.
|
|
|
|
2. Launch a VM (VM on which you want to monitor/receive the mirrored data).
|
|
Associate the Neutron port created in step 1 while creating the VM.
|
|
|
|
3. Using Neutron Client command for TaaS **neutron tap-service-create** or
|
|
via REST APIs create a Tap Service instance by associating the port
|
|
created in step 1.
|
|
|
|
4. Using Neutron Client command for TaaS **neutron tap-flow-create** or
|
|
via REST APIs create a Tap Flow instance by associating the Tap Service
|
|
instance created in step 3 and the target Neutron port from which you want
|
|
to mirror traffic (assuming the Neutron port from which the traffic
|
|
needs to be monitored already exists.)
|
|
Mirroring can be done for both incoming and/or outgoing traffic from the
|
|
target Neutron port.
|
|
|
|
5. Observe the mirrored traffic on the monitoring VM by running tools such as
|
|
tcpdump.
|