[spp] [PATCH v4 01/14] docs: add overview of spp-ctl

[oda at valinux.co.jp]

From: Itsuro Oda <oda at valinux.co.jp>

Add overview section of spp-ctl.

Signed-off-by: Itsuro Oda <oda at valinux.co.jp>
---
 docs/guides/spp-ctl/overview.rst | 119 +++++++++++++++++++++++++++++++
 1 file changed, 119 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..4c7181c
--- /dev/null
+++ b/docs/guides/spp-ctl/overview.rst
@@ -0,0 +1,119 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Nippon Telegraph and Telephone Corporation
+
+.. _spp_ctl_overview:
+
+spp-ctl
+=======
+
+Overview
+--------
+
+``spp-ctl`` is an alternative SPP controller which provides a REST-like
+APIs.
+
+It maintains connections between SPP processes for managing them
+via the REST-like APIs for users or other processes.
+
+Background and Motivation
+-------------------------
+
+``spp-ctl`` is designed for supporting to manage SPP from several
+controllers.
+
+There are some usecases where SPP is managed from other
+process without user inputs.
+For example, you need a intermediate process if you think of using SPP
+from a framework, such as OpenStack.
+`networking-spp
+<https://github.com/openstack/networking-spp>`_
+is a Neutron ML2 plugin for SPP and `spp-agent` works as a
+SPP controller.
+
+It is a problem to prepare several controllers for each of usages for
+CLI, OpenStack or others because it would be hard to maintain for
+updates.
+
+Spp-ctl is designed to solve the problem of several controllers with
+application-independent REST APIs.
+You can manage SPP by requesting via this APIs.
+
+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
+<https://bottlepy.org/docs/dev/>`_
+which is simple and well known as a web framework and
+`eventlet
+<http://eventlet.net/>`_
+for parallel processing.
+``spp-ctl`` accepts multiple requests at the same time and serializes them
+internally.
+
+
+Setup
+=====
+
+You are required to install Python3 and packages described in
+``requirements.txt`` via ``pip3`` for launching ``spp-ctl``.
+You might need to run ``pip3`` with ``sudo``.
+
+.. code-block:: console
+
+    $ sudo apt update
+    $ sudo apt install python3
+    $ sudo apt install python3-pip
+    $ pip3 install -r requirements.txt
+
+Usage
+-----
+
+.. code-block:: console
+
+    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
+-------------
+
+`spp-ctl` is assumed to be launched as a daemon process, or managed
+by `systemd`.
+Here is a simple example of service file for systemd.
+
+::
+
+    [Unit]
+    Description = SPP Controller
+
+    [Service]
+    ExecStart = /usr/bin/python3 /path/to/spp/src/spp-ctl/spp-ctl
+    User = root
+
+
+REST APIs
+=========
+
+You can try to call ``spp-ctl`` APIs with ``curl`` command as following.
+
+.. code-block:: console
+
+    $ curl http://localhost:7777/v1/processes
+    [{"type": "primary"}, ..., {"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"}'
+
+For more details, see
+:ref:`API Reference<spp_ctl_api_ref>`.
-- 
2.17.1