ODPM 606: Clean up docs, flavors, cmd.

Author: Milan Lenco

cmd/README.md

@@ -4,10 +4,11 @@ This package groups executables that can be built from sources in the VPP
 Agent repository:
 
 - [vpp-agent](vpp-agent/main.go) - the default off-the-shelf VPP Agent 
-  executable (i.e. no app or extension plugins) that can be bundled with an
-  off-the-shelf VPP to form a simple cloud-native VNF, such as a vswitch.
-- [agentctl](agentctl/agentctl.go) - CLI tool that allows to show the state 
-  and to configure VPP Agents connected to etcd
-- [vpp-agent-ctl](vpp-agent-ctl/main.go) - a utility for testing VPP Agent 
-  configuration. It contains a set of hard-wired configurations that can 
-  be invoked using command line flags and sent to the VPP Agent.
+  executable (i.e. no app or extension plugins) that can be bundled with
+  an off-the-shelf VPP to form a simple cloud-native VNF,
+  such as a vswitch.
+- [agentctl](agentctl/agentctl.go) - CLI tool that allows to show
+  the state and to configure VPP Agents connected to etcd
+- [vpp-agent-ctl](vpp-agent-ctl/main.go) - a utility for testing VPP
+  Agent configuration. It contains a set of hard-wired configurations
+  that can be invoked using command line flags and sent to the VPP Agent.

cmd/vpp-agent/main.go

@@ -28,10 +28,10 @@ import (
 
 // main is the main entry point into the VPP Agent. First, a new CN-Infra
 // Agent (app) is created using the set of plugins defined in vpp_flavor
-// (github.com/ligato/vpp-agent/flavors/vpp). Second, function call to
-// EventLoopWithInterrupt()) initializes and starts all plugins and then
-// waits for the user to terminate the VPP Agent process. All VPP Agent's
-// work from now on is performed by the plugins.
+// (../../flavors/vpp). Second, the function calls EventLoopWithInterrupt()
+// which initializes and starts all plugins and then waits for the user
+// to terminate the VPP Agent process with SIGINT. All VPP Agent's work between
+// the initialization and termination is performed by the plugins.
 func main() {
 
 	f := vpp_flavor.Flavor{}

docs/Deployment.md

@@ -1,14 +1,15 @@
 # Deployment
 
-VPP Agent can run on any server where VPP is installed. It can run on bare
-metal, in a VM, or in a container.
+VPP Agent can run on any server where VPP is installed. It can run
+on a bare metal, in a VM, or in a container.
 
-Benefits of putting a VPP-based VNF (bascially, just VPP and the VPP Agent) 
-into a container are:
- * simplified upgrades and bringup/shutdown, and better scaling  
- * Container-based VNFs are in essence data plane lightweight and reusable 
-   data plane microservices which can be used to build lrger systems and 
-   applications
+Benefits of putting a VPP-based VNF (basically just a combination of VPP
+and the VPP Agent) into a container are:
+ * simplified upgrades and startup/shutdown, which results in improved
+   scalability
+ * Container-based VNFs are in essence lightweight and reusable
+   data-plane microservices which can be used to build larger systems
+   and applications
  * supports container healing 
 
 ## K8s integration
@@ -21,39 +22,41 @@ The following diagram shows VPP deployement in:
 ![K8s integration](imgs/k8s_deployment.png "VPP Agent - K8s integration")
 
 K8s:
-- starts/stops the containers on multiple hosts
-- checks containers health (using probes - HTTP calls)
+- starts/stops the containers running on multiple hosts
+- checks health of the individual containers (using probes - HTTP calls)
 
-## NB (Nort-bound) configuration vs. deployment
+## NB (North-bound) configuration vs. deployment
 VPP + Agent can be deployed in different environments. Several deployment 
-alternatives are briefly described in the following sub-chapters. Regardless
-of the deployment, the VPP Agent can be configured using the same Client v1
-interface. There are three different implementations of the interface:
+alternatives are briefly described in the following sub-chapters.
+Regardless of the deployment, the VPP Agent can be configured using
+the same Client v1 interface. There are three different implementations
+of the interface:
  - local client
  - remote client using Data Broker
  - remote client using GRPC
 
 ### Key Value Data Store for NB
-The Control Plane using remote client writes configuration to the Data Store 
-(tested with ETCD, Redis). VPP Agent watches particular key prefixes in Data 
-Store using dbsync package.
+The Control Plane writes configuration to the Data Store using a remote
+client (tested with ETCD, Redis). VPP Agent watches dedicated key
+prefixes in Data Store using dbsync package.
 
 ![deployment with data store](imgs/deployment_with_data_store.png)
 TBD links to the code
 
-### GRPC 
-The Control Plane using remote client sends configuration to the Data Store 
-(tested with ETCD, Redis). VPP Agent watches particular key prefixes in Data 
+### GRPC
+The Control Plane using remote client sends configuration to the Data
+Store (tested with ETCD, Redis). VPP Agent watches particular key prefixes in Data
 Store using grpcsync package.
 
 ![grpc northbound](imgs/deployment_nb_grpc.png)
 TBD links to the code
 
 ### Embedded deployment
-VPP Agent can be embedded in a different project. For integration with 
-[Contiv](http://contiv.github.io/) we use the embedded deployment. In this 
-case the VPP Agent gets the configuration from Local client v1 through 
-in-memory calls (Go API).
+VPP Agent can be directly embedded into a different project.
+For integration with [Contiv](http://contiv.github.io/) we decided to
+embed the VPP Agent directly into the netplugin process as a new driver
+for VPP-based networking. Using the Local client v1 the driver is able
+to propagate the configuration into the Agent via Go channels.
 
 ![embeded deployment](imgs/deployment_embeded.png)
 TBD links to the code

docs/Design.md

@@ -3,34 +3,35 @@
 
 Brief description:
 * **SFC Controller** - renders a logical network topology (which defines
-  how VNF are logically interconnected) onto a given physical network, and
-   VNF placement; the rednering process creates configuration for VNFs and
-   network devices. 
+  how VNF are logically interconnected) onto a given physical network
+  and VNF placement; the rendering process creates configuration for VNFs
+  and network devices.
 
 * **Control Plane Apps** - renders specific VPP configuration for multiple 
   agents to the Data Store
 
-* **Clientv1** - VPP Agent clients clients(app, tools, the control plane)
- can use the clientv1 library to interact with one or more VPP Agents. The
-  clientv1 library is based on generated GO structures from protobuf 
-  messages. The library contais helper methods for working with KV Data 
-  Stores used for generation of keys and storing/retrieving data in the 
-  Data Store under a given key.
+* **Clientv1** - VPP Agent clients (control plane apps & tools)
+  can use the clientv1 library to interact with one or more VPP Agents.
+  The clientv1 library is based on generated GO structures from protobuf
+  messages. The library contains helper methods for working with KV Data
+  Stores, used for generation of keys and storage/retrieval
+  of configuration data to/from Data Store under a given key.
 
-* **Data Store** (ETCD, Redis, etc.) to:
-  * Store VPP configuration; this data is put into the Data Store by one
+* **Data Store** (ETCD, Redis, etc.) is used to:
+  * store VPP configuration; this data is put into the Data Store by one
     or more orchestrator apps and retrieved by one or more VPP Agents.
-  * Store operational state, such as network counters /statistics or errors; 
-    this data is put into the Data Store by one or more VPP Agents and 
-    retrieved by one or more monitoring/analytics applications. 
+  * store operational state, such as network counters /statistics
+    or errors; this data is put into the Data Store by one or more VPP
+    Agents and retrieved by one or more monitoring/analytics applications.
 
-* **VPP vSwitch** - privileged container that cross connects multiple VNFs
+* **VPP vSwitch** - privileged container that cross-connects multiple VNFs
 
 * **VPP VNF** - a container with a Virtual Network Function implementation 
-  based on  VPP 
+  based on VPP
 
 * **Non VPP VNF** - container with a non-VPP based Virtual Network Function;
-  that can nevertheless interact with VPP containers (see below MEMIFs, VETH)
+  that can nevertheless interact with VPP containers (see below MEMIFs,
+  VETH)
 
 * **Messaging** - AD-HOC events (e.g. link UP/Down)
 
@@ -42,55 +43,55 @@ The VPP Agent was designed to meet the following requirements:
 * Rapid deployment
 * High performance & minimal footprint
 
-
 ## Modular design with API contract
-The VPP Agent code base is a collection of plugins. Each plugin provides
-a specific service defined by the service's API. VPP Agent's functionality
-can be easily extended by introducing new plugins. Well-defined API 
-contracts facilitate integration of new plugins into the VPP Agent or 
-integration of multiple plugins into a new application.
+The VPP Agent codebase is basically a collection of plugins.
+Each plugin provides a specific service defined by the service's API.
+VPP Agent's functionality can be easily extended by introducing new
+plugins. Well-defined API contracts facilitate seamless integration
+of new plugins into the VPP Agent or integration of multiple plugins
+into a new application.
 
 ## Cloud native
-Assumption: both data plane and control plane can be implemented as a set 
-of microservices, where each microservice is independent of other 
-microservices. Therefore, the overall configuration of a system may be 
-incomplete at times, since one object may refer to another object owned by
-a service that has not been instantiated yet. The VPP agent can handle this
-use - at first it skips incomplete part of configuration, and later, when
-the configuration is updated, it tries again to configure what was skipped.
+*Assumption*: both data plane and control plane can be implemented as
+a set of microservices independent of each other. Therefore, the overall
+configuration of a system may be incomplete at times, since one object
+may refer to another object owned by a service that has not been
+instantiated yet. The VPP agent can handle this case - at first it skips
+the incomplete parts of the overall configuration, and later, when
+the configuration is updated, it tries again to configure what has been
+previously skipped.
 
 The VPP Agent is usually deployed in a container together with VPP. There
 can be many of these containers in a given cloud or in a more complex data 
 plane implementation. Containers can be used in many different 
 infrastructures (on-premise, hybrid, or public cloud). The VPP + VPP Agent 
 containers have been tested with [Kubernetes](https://kubernetes.io/).
 
-
 Control Plane microservices do not really depend on the current lifecycle
 phase of the VPP Agents. Control Plane can render config data for one or 
 more VPP Agents and store it in the KV Data Store even if (some of) the 
 VPP Agents have not been started yet. This is possible because:
-- The Control Plane does not access the VPP Agents directly, but it rather 
-  accesses the KV Data Store; the VPP Agents are responsible for downloading
-  their data from the Data Store. 
+- The Control Plane does not access the VPP Agents directly, instead it
+  accesses the KV Data Store; the VPP Agents are responsible
+  for downloading their data from the Data Store.
 - Data structures in configuration files use logical object names, not 
   internal identifiers of the VPP). See the 
   [protobuf](https://developers.google.com/protocol-buffers/) 
   definitions in the `model` sub folders in various VPP Agent plugins. 
 
-## Fault tolerant
+## Fault tolerance
 Each microservice has its own lifecycle, therefore the VPP Agent is 
 designed to recover from HA events even when some subset of microservices 
 (e.g. db, message bus...) are temporary unavailable.
 
 The same principle can be applied also for the VPP Agent process and the
 VPP process inside one container. The VPP Agent checks the VPP actual 
-configuration and does data synchronization by polling latest configuration
-from the KV Data Store.
+configuration and does data synchronization by polling latest
+configuration from the KV Data Store.
 
 VPP Agent also reports status of the VPP in probes & Status Check Plugin.  
 
-In general VPP Agents:
+In general, VPP Agents:
  * propagate errors to upper layers & report to the Status Check Plugin
  * fault recovery is performed with two different strategies:
    * easily recoverable errors: retry data synchronization (Data Store 
@@ -101,13 +102,13 @@ In general VPP Agents:
 ## Rapid deployment
 
 Containers allow to reduce deployment time to seconds. This is due to the 
-fact that containers are created at process level  and there is no need to 
-boot the OS. More over K8s helps with (un)deploying different version of 
-multiple instances of microservices.
+fact that containers are created at process level and there is no need to
+boot an OS. Moreover, K8s helps with the (un)deployment of possibly
+different versions of multiple microservice instances.
 
 ## High performance & minimal footprint
-Performance optimization is currently work in progress. Several bottlenecks
-that can be optimized have been identified:
+Performance optimization is currently a work-in-progress.
+Several bottlenecks that can be optimized have been identified:
 - GOVPP
 - minimize context switching
-- replace blocking calls to non-blocking calls
+- replace blocking calls to non-blocking (asynchronous) calls

docs/Extensibility.md

@@ -1,10 +1,18 @@
-
-
 # Extensibility
 The following code snippet illustrates how to start a new flavor of plugins.
 The complete code can be found [here](https://github.com/ligato/cn-infra/blob/master/examples/simple-agent/agent.go).
 
 ```
 func main() {
+	logroot.StandardLogger().SetLevel(logging.DebugLevel)
+
+	connectors := connectors.AllConnectorsFlavor{}
+	rpcs := rpc.FlavorRPC{}
+	agent := core.NewAgent(logroot.StandardLogger(), 15*time.Second, append(
+		connectors.Plugins(), rpcs.Plugins()...)...)
+
+	err := core.EventLoopWithInterrupt(agent, nil)
+	if err != nil {
+		os.Exit(1)
 }
 ```

flavors/local/local_flavor.go

@@ -27,7 +27,8 @@ import (
 	"github.com/ligato/vpp-agent/plugins/linuxplugin"
 )
 
-// FlavorVppLocal glues together multiple plugins to mange VPP and linux interfaces configuration using local client.
+// FlavorVppLocal glues together multiple plugins to manage VPP and Linux
+// configuration using the local client.
 type FlavorVppLocal struct {
 	*local.FlavorLocal
 	LinuxLocalClient localclient.Plugin
@@ -38,7 +39,7 @@ type FlavorVppLocal struct {
 	injected bool
 }
 
-// Inject sets object references
+// Inject sets inter-plugin references.
 func (f *FlavorVppLocal) Inject() error {
 	if f.injected {
 		return nil
@@ -60,7 +61,7 @@ func (f *FlavorVppLocal) Inject() error {
 	return nil
 }
 
-// Plugins combines Generic Plugins and Standard VPP Plugins
+// Plugins combines all Plugins in the flavor to a list.
 func (f *FlavorVppLocal) Plugins() []*core.NamedPlugin {
 	f.Inject()
 	return core.ListPluginsInFlavor(f)