[spp] [PATCH v2 1/9] docs: overview

[Yasufumi Ogawa]

On 2018/09/23 11:25, Itsuro ODA wrote:
> From: Itsuro Oda <oda at valinux.co.jp>
> 
Hi,

Could you consider to update this patch for the listed below.

* Add license and copyright holder at the top of the file.

* Correct description of link to the API reference is not incorrect and does not work. Here is a right example.
For more details, see
:ref:`API Reference<spp_ctl_api_ref>`.

* Update "code-block" directive to specify the type of codes.
.. code-block:: console
.. code-block:: json
etc.

Thanks,
Yasufumi

> Signed-off-by: Itsuro Oda <oda at valinux.co.jp>
> ---
>   docs/guides/spp-ctl/overview.rst | 102 +++++++++++++++++++++++++++++++
>   1 file changed, 102 insertions(+)
>   create mode 100644 docs/guides/spp-ctl/overview.rst
> 
> diff --git a/docs/guides/spp-ctl/overview.rst b/docs/guides/spp-ctl/overview.rst
> new file mode 100644
> index 0000000..847b9dc
> --- /dev/null
> +++ b/docs/guides/spp-ctl/overview.rst
> @@ -0,0 +1,102 @@
> +====================================
> +spp-ctl: SPP controller with Web API
> +====================================
> +
> +Overview
> +========
> +
> +spp-ctl is a SPP controller with a REST like web API.
> +
> +spp-ctl maintains the connections from the SPP processes and at the same
> +time exposes the API for the user to request for the SPP processes.
> +
> +Background and motivation
> +-------------------------
> +
> +Current CLI (spp.py/spp_vf.py) can be used by intaractive only.
> +Therefore, spp-agent, a component of networking-spp which make SPP
> +available on OpenStack environment, implements SPP controller in
> +itself. (see. https://github.com/openstack/networking-spp )
> +
> +Either CLI or spp-agent, there is a problem that other people can not
> +request to SPP processes while using. spp-ctl is invented to solve this
> +problem.
> +
> +Both CLI and spp-agent can be used spp-ctl to request SPP processes
> +instead of owning contoroller itself. In that case, multiple people
> +can request to SPP processes at the same time.
> +Note that spp-agent has a plan to change to use spp-ctl.
> +It is also available not using CLI but requesting spp-ctl directly.
> +
> +Architecture
> +------------
> +
> +The design goal of spp-ctl is to be as simple as possible.
> +It is stateless. Basically, spp-ctl only converts API requests into
> +commands of SPP processes and throws request, thouth it does syntax and
> +lexical check for API requests.
> +
> +spp-ctl adopts bottle (it is simple and well known) as a web framework
> +and eventlet for parallel processing. spp-ctl can process multiple APIs
> +at the same time, however, requests for per SPP process are serialized
> +internally.
> +
> +
> +Setup
> +=====
> +
> +spp-ctl is a simple program written in python3. Installation of related
> +packages is as follows (assume ubuntu).
> +
> +::
> +
> +  $ sudo apt update
> +  $ sudo apt install python3
> +  $ sudo apt install python3-pip
> +  $ sudo pip3 install -r requirements.txt
> +
> +Usage
> +-----
> +
> +::
> +
> +  usage: spp-ctl [-p PRI_PORT] [-s SEC_PORT] [-a API_PORT]
> +
> +  optional arguments:
> +    -p PRI_PORT  primary port. default is 5555.
> +    -s SEC_PORT  secondary port. default is 6666.
> +    -a API_PORT  web api port. default is 7777.
> +
> +Using systemd
> +-------------
> +
> +Although spp-ctl runs as a daemon process normaly, it assumes to the
> +use of systemd and does not daemonize itself.
> +
> +The service file for systemd is simple as shown below::
> +
> +  [Unit]
> +  Description = SPP Controller
> +
> +  [Service]
> +  ExecStart = {SPP install path}/spp_ctl/spp-ctl -p 5555 -s 6666 -a 7777
> +  User = root
> +
> +API Usage
> +=========
> +
> +For API details, see API-reference_.
> +
> +.. _API-reference: ./api-reference.rst
> +
> +Since spp-ctl provides the web API, for example, you can use curl to execute
> +requests as follows::
> +
> +  $ curl http://localhost:7777/v1/processes
> +  [{"type": "primary"}, {"client-id": 1, "type": "vf"}, {"client-id": 2, "type": "vf"}]
> +  $ curl http://localhost:7777/v1/vfs/1
> +  ... snip
> +  $ curl -X POST http://localhost:7777/v1/vfs/1/components \
> +    -d '{"core": 2, "name": "forward_0_tx", "type": "forward"}'
> +  $
> +
> 


-- 
Yasufumi Ogawa
NTT Network Service Systems Labs