From 85ceef58b6c248155031a60e66d3bb988ccd3926 Mon Sep 17 00:00:00 2001 From: Ondrej Fabry Date: Wed, 5 Jun 2019 13:15:06 +0200 Subject: [PATCH] Update README.md --- README.md | 150 ++++++++++++++++++++++++------------------------------ 1 file changed, 67 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 4216a5b2a..f2849ee03 100644 --- a/README.md +++ b/README.md @@ -11,87 +11,18 @@ control plane agents for cloud-native Virtual Network Functions It is basically a collection of components/libraries used in most control plane agents tied together with a common life-cycle management mechanism. -#### Available CN-Infra Plugins: - -A CN-Infra plugin is typically implemented as a library providing the -plugin's functionality/APIs wrapped in a plugin wrapper. A CN-Infra -library can also be used standalone in 3rd party apps that do not use -the CN-Infra framework. The plugin wrapper provides lifecycle management -for the plugin component. - -Plugins in the current CN-Infra release provide functionality in one of -the following functional areas: +## Documentation -* **RPC** - allows to expose application's API: - - [GRPC][docs-grpc] - handles GRPC requests and allows app plugins to define - their own GRPC services - - [REST][docs-rest] - handles HTTP requests and allows app plugins to define - their own REST APIs - - Prometheus - serves Prometheus metrics via HTTP and allows - app plugins to register their own collectors - -* **Data Stores** - provides a common data store API for app plugins (the - Data Broker) and back-end clients. The data store related plugins are: - - [Consul][docs-consul] - key-value data store adpater for Consul - - [Etcd][docs-etcd] - key-value data store adpater for Etcd - - [Redis][docs-redis] - key-value data store adpater for Redis - - [Casssandra][cassandra] - key-value data store adpater for Cassandra - - [FileDB][docs-filedb] - key-value data store using OS filesystem - -* **Messaging** - provides a common API and connectivity to message buses: - - [Kafka][docs-kafka] - adapter for the Kafka message bus (built on top of - Sarama) - -* **Logging**: - - [Logrus wrapper][logrus] - implements logging skeleton - using the Logrus library. An app writer can create multiple loggers - - for example, each app plugin can have its own logger. Log level - for each logger can be controlled individually at run time through - the Log Manager REST API. - - [Log Manager][docs-logmanager] - allows the operator to set log - level for each logger using a REST API. - -* **Health Monitoring** - Self health check mechanism between plugins - plus RPCs: - - [StatusCheck][docs-statuscheck] - allows to monitor the status of plugins - and exposes it via HTTP - - [Probe][probe] - callable remotely from K8s - -* **Miscellaneous** - value-add plugins supporting the operation of a - CN-Infra based application: - - [Config][config] - helpers for loading plugin configuration. - - [Datasync][resync] - provides data resynchronization after HA - events (restart or connectivity restoration after an outage) for data - stores, gRPC and REST. - - [IDX Map][idx-map] - reusable thread-safe map with advanced features: - * multiple subscribers for watching changes in the map - * secondary indexes - - [ServiceLabel][docs-service-label] - provides setting and retrieval of a - unique identifier for a CN-Infra based app. A cloud app typically needs - a unique identifier so that it can differentiated from other instances - of the same app or from other apps (e.g. to have its own space in a kv - data store). +Extensive documentation with tutorials & how-to guides can be found at [docs.ligato.io](https://docs.ligato.io/). +Documentation for the code can be found at [godoc.org/github.com/ligato/cn-infra](https://godoc.org/github.com/ligato/cn-infra). ## Quickstart -You can run this example code by using pre-build Docker images: - -For quick start with the VPP Agent, you can use pre-build Docker images with the Agent and VPP -on [Dockerhub][dockerhub]. - -1. Run ETCD and Kafka on your host (e.g. in Docker - [using this procedure][simple-agent]). - -2. Run cn-infra example [simple-agent][simple-agent]. -``` -docker pull ligato/dev-cn-infra -docker run -it --name dev-cn-infra --rm ligato/dev-cn-infra -``` - A very simple example of a control plane agent that uses Etcd as its configuration data store is as follows: -``` + +```go func main() { // Create agent with connector plugins @@ -108,12 +39,6 @@ func main() { You can find the above example [here][simple-agent], from where it can be compiled and run in your favorite environment. -## Documentation - -Detailed documentation (including tutorials) can be found [here][ligato]. - -GoDocs can be browsed [online][godocs]. - ## Architecture Each management/control plane app built on top of the CN-Infra framework is @@ -152,7 +77,68 @@ are required by their app; for example, if an app does not need a KV store, the CN-Infra framework KV data store plugins would not be included in the app. All plugins used in an app are statically linked into the app. - + +### Available CN-Infra Plugins: + +A CN-Infra plugin is typically implemented as a library providing the +plugin's functionality/APIs wrapped in a plugin wrapper. A CN-Infra +library can also be used standalone in 3rd party apps that do not use +the CN-Infra framework. The plugin wrapper provides lifecycle management +for the plugin component. + +Plugins in the current CN-Infra release provide functionality in one of +the following functional areas: + +* **RPC** - allows to expose application's API: + - [GRPC][docs-grpc] - handles GRPC requests and allows app plugins to define + their own GRPC services + - [REST][docs-rest] - handles HTTP requests and allows app plugins to define + their own REST APIs + - Prometheus - serves Prometheus metrics via HTTP and allows + app plugins to register their own collectors + +* **Data Stores** - provides a common data store API for app plugins (the + Data Broker) and back-end clients. The data store related plugins are: + - [Consul][docs-consul] - key-value data store adpater for Consul + - [Etcd][docs-etcd] - key-value data store adpater for Etcd + - [Redis][docs-redis] - key-value data store adpater for Redis + - [Casssandra][cassandra] - key-value data store adpater for Cassandra + - [FileDB][docs-filedb] - key-value data store using OS filesystem + +* **Messaging** - provides a common API and connectivity to message buses: + - [Kafka][docs-kafka] - adapter for the Kafka message bus (built on top of + Sarama) + +* **Logging**: + - [Logrus wrapper][logrus] - implements logging skeleton + using the Logrus library. An app writer can create multiple loggers - + for example, each app plugin can have its own logger. Log level + for each logger can be controlled individually at run time through + the Log Manager REST API. + - [Log Manager][docs-logmanager] - allows the operator to set log + level for each logger using a REST API. + +* **Health Monitoring** - Self health check mechanism between plugins + plus RPCs: + - [StatusCheck][docs-statuscheck] - allows to monitor the status of plugins + and exposes it via HTTP + - [Probe][probe] - callable remotely from K8s + +* **Miscellaneous** - value-add plugins supporting the operation of a + CN-Infra based application: + - [Config][config] - helpers for loading plugin configuration. + - [Datasync][resync] - provides data resynchronization after HA + events (restart or connectivity restoration after an outage) for data + stores, gRPC and REST. + - [IDX Map][idx-map] - reusable thread-safe map with advanced features: + * multiple subscribers for watching changes in the map + * secondary indexes + - [ServiceLabel][docs-service-label] - provides setting and retrieval of a + unique identifier for a CN-Infra based app. A cloud app typically needs + a unique identifier so that it can differentiated from other instances + of the same app or from other apps (e.g. to have its own space in a kv + data store). + ## Contributing If you are interested in contributing, please see the [contribution guidelines](CONTRIBUTING.md). @@ -170,9 +156,7 @@ If you are interested in contributing, please see the [contribution guidelines]( [docs-redis]: https://docs.ligato.io/en/latest/plugins/db-plugins/#redis [docs-rest]: https://docs.ligato.io/en/latest/plugins/connection-plugins/#rest-plugin [docs-service-label]: https://docs.ligato.io/en/latest/plugins/infra-plugins/#service-label -[godocs]: https://godoc.org/github.com/ligato/vpp-agent [idx-map]: idxmap -[ligato]: https://docs.ligato.io [logrus]: logging/logrus [probe]: health/probe [resync]: datasync/resync