summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBin Hu <bh526r@att.com>2017-03-02 15:50:28 -0800
committerBin Hu <bh526r@att.com>2017-03-03 09:33:30 -0800
commit87f4ebd1a9d5f1450d56742279bab6cf37572560 (patch)
treef99ca58cde15b9a071b2765273f67d0955b67128
parenta1c9d2ee18a543c0c2e3f3641ac7ff05f480bdb1 (diff)
Draft of Gluon User Guide for NetReady
Change-Id: I1bcfe2191c7126bd324f4f7c392f27bb219a158a Signed-off-by: Bin Hu <bh526r@att.com>
-rw-r--r--docs/release/userguide/feature.userguide.rst235
1 files changed, 226 insertions, 9 deletions
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
index 69236c6..6739146 100644
--- a/docs/release/userguide/feature.userguide.rst
+++ b/docs/release/userguide/feature.userguide.rst
@@ -10,18 +10,235 @@ OPNFV NetReady User Guide
:depth: 3
:local:
-Gluon description
+Gluon Description
-----------------
-.. Describe the specific features and how it is realised in the scenario in a brief manner
-.. to ensure the user understand the context for the user guide instructions to follow.
-Gluon capabilities and usage
+**Gluon** brings a Networking Service Framework that enables Telecom Service
+Providers to provide their customers with networking services on-demand.
+**Gluon** uses a model-driven approach to generate Networking Service APIs
+(including objects, database schema, and RESTful API endpoints) from a YAML
+file which models the Networking Service. When a Telecom Service Provider
+needs to launch a new Networking Service, it only needs to model the new
+service in a YAML file. The **Gluon** framework generates the APIs accordingly.
+Thus **Gluon** helps Telecom Service Providers accelerate the time-to-market
+and achieve business agility through its extensibility and scalability in
+generating APIs for new use-cases and services.
+
+Gluon Capabilities and Usage
----------------------------
-.. Describe the specific capabilities and usage for <XYZ> feature.
-.. Provide enough information that a user will be able to operate the feature on a deployed scenario.
-Gluon API guidelines and examples
+**Gluon** is the port arbiter that maintains a list of ports and bindings of
+different networking backends. A **Proton** is a set of APIs of a particular
+NFV Networking Service. A **Proton Server** is the API server that hosts
+multiple **Protons**, i.e. multiple sets of APIs. **Gluon** uses backend
+drivers to interact with the **Proton Server** for port binding and other
+operations.
+
+A **Proton** is created by a **Particle Generator** based on a YAML file modeled
+for this particular NFV Networking Service. When a **Proton** is created, the
+objects, database schema, and RESTful APIs of this **Proton** are created.
+Then the **Proton** specific driver would be loaded into **Gluon**.
+
+When the **Proton Server** receives port binding and other operation requests,
+it broadcasts those requests to ``etcd``. The **Shim Layers** of respective
+SDN Controllers listen to ``etcd``, and get the notification from ``etcd``.
+Based on the type of operations, parameter data, and its own deployment and
+policy configuration, SDN Controllers act upon accordingly. This mechanism is
+similar to Neutron's Hierarchical Port Binding (HPB), and provides the
+flexibility and scalability when a port operation needs to be supported by
+multiple SDN Controllers in collaborative and interoperable way.
+
+Gluon API Guidelines and Examples
---------------------------------
-.. Describe with examples how to use specific features, provide API examples and details required to
-.. operate the feature on the platform.
+
+This section shows you how to use **Proton** to create the needed objects,
+and then use ``nova boot`` to bind the port to a VM. It is assumed that you
+have already installed Gluon package, including ``etcd`` and **Gluon Plugin**,
+and started **Proton Server**. If not, please refer to [1]_.
+
+Getting Help
+~~~~~~~~~~~~
+
+Just typing the ``protonclient --help`` command gives you general help
+information:
+
+.. code-block:: bash
+
+ $ protonclient --help
+
+ Usage: protonclient --api <api_name> [OPTIONS] COMMAND[ARGS]...
+
+ Options:
+ --api TEXT Name of API, one of ['net-l3vpn', 'test']
+ --port INTEGER Port of endpoint (OS_PROTON_PORT)
+ --host TEXT Host of endpoint (OS_PROTON_HOST)
+ --help Show this message and exit.
+
+Mandatory Parameters
+~~~~~~~~~~~~~~~~~~~~
+
+``--api <api_name>`` is a mandatory parameter. For example, ``--api net-l3vpn``.
+
+Just typing the ``protonclient`` command shows you that those mandatory
+parameters are required, and gives you general help information too.
+
+.. code-block:: bash
+
+ $ protonclient
+ --api is not specified!
+
+ Usage: protonclient --api <api_name> [OPTIONS] COMMAND[ARGS]...
+
+ Options:
+ --api TEXT Name of API, one of ['net-l3vpn', 'test']
+ --port INTEGER Port of endpoint (OS_PROTON_PORT)
+ --host TEXT Host of endpoint (OS_PROTON_HOST)
+ --help Show this message and exit.
+
+Using L3VPN Proton
+~~~~~~~~~~~~~~~~~~
+
+**NOTE** that there is a KNOWN BUG in the **Usage** message where the mandatory
+parameters ``--api net-l3vpn`` are missing.
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn
+ Usage: protonclient [OPTIONS] COMMAND [ARGS]...
+
+ Options:
+ --help Show this message and exit.
+
+ Commands:
+ interface-create
+ interface-delete
+ interface-list
+ interface-show
+ interface-update
+ port-create
+ port-delete
+ port-list
+ port-show
+ port-update
+ vpn-create
+ vpn-delete
+ vpn-list
+ vpn-show
+ vpn-update
+ vpnafconfig-create
+ vpnafconfig-delete
+ vpnafconfig-list
+ vpnafconfig-show
+ vpnafconfig-update
+ vpnbinding-create
+ vpnbinding-delete
+ vpnbinding-list
+ vpnbinding-show
+ vpnbinding-update
+
+The following sections give you the general work flow of how to use Proton to
+create and configure an L3VPN.
+
+**For more details and examples, please refer to [2]_**.
+
+Work Flow of Using L3VPN
+++++++++++++++++++++++++
+
+The work flow of using L3VPN includes:
+
+* **Step 1: Create ``Port`` Object**
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn port-create --help
+ $ protonclient --api net-l3vpn port-create [ARGS] ...
+
+Please **NOTE**: a default ``interface`` object is automatically created too
+when a ``Port`` is created, and this default ``interface`` object is attached
+to this ``Port`` object. The UUID of this default ``Interface`` object
+will be the same as the UUID of the parent ``Port`` object.
+
+* **Step 2 (Optional): Create ``Interface`` Object**
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn interface-create --help
+ $ protonclient --api net-l3vpn interface-create [ARGS] ...
+
+Please **NOTE**: This step is optional because a default ``Interface`` object
+was already automatically created when a ``Port`` object was created at
+**Step 1**.
+
+ * **For example: list the default ``Interface`` Object**:
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn interface-list
+
+* **Step 3 (Optional): Create ``VPNAFConfig`` Object**
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn vpnafconfig-create --help
+ $ protonclient --api net-l3vpn vpnafconfig-create [ARGS] ...
+
+Please **NOTE**: This step is optional because all parameters needed for an
+L3VPN (route specifiers) are also present in creating a ``VPN`` service object
+at **Step 4**. This part of the API needs to be aligned in the future.
+
+* **Step 4: Create ``VPN`` Object**
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn vpn-create --help
+ $ protonclient --api net-l3vpn vpn-create [ARGS] ...
+
+At this point you have a ``Port`` object, default ``Interface`` object and a
+``VPN`` service object created.
+
+ * View ``VPN`` and ``Port`` Objects
+
+You can view the values with the following commands:
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn vpn-list
+ $ protonclient --api net-l3vpn port-list
+
+* **Step 5: Create ``VPNBinding`` Object**
+
+You need to create a ``VPNBinding`` object to tie the ``Interface`` and the
+``Service`` together in order to achieve service binding.
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn vpnbinding-create --help
+ $ protonclient --api net-l3vpn vpnbinding-create [ARGS] ...
+
+ * View ``VPNBinding`` Objects
+
+.. code-block:: bash
+
+ $ protonclient --api net-l3vpn vpnbinding-list
+
+At this point you have had all of the information needed for an L3VPN Port in
+Proton.
+
+* **Step 6: Create VM and Bind our L3VPN Port**
+
+.. code-block:: bash
+
+ $ nova --debug boot --flavor 1 --image cirros --nic port-id=<port-id> <VM-Name>
+
+To Use Gluon in a Project
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ import gluon
+
+References
+
+.. [1] ../installation/index
+.. [2] https://github.com/openstack/gluon/blob/master/doc/source/usage.rst