README.md

CN-Infra

CN-Infra (cloud-native infrastructure) is a Golang framework for building 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.

Documentation

Extensive documentation with tutorials & how-to guides can be found at docs.ligato.io.

Quickstart

A very simple example of a control plane agent that uses Etcd as its configuration data store is as follows:

func main() {
	// Create agent with connector plugins
	a := agent.NewAgent(agent.AllPlugins(
		&etcd.DefaultPlugin,
		&resync.DefaultPlugin,
	))

	if err := a.Run(); err != nil {
		log.Fatal(err)
	}
}

You can find the above example here, from where it can be compiled and run in your favorite environment.

Architecture

Each management/control plane app built on top of the CN-Infra framework is basically a set of modules called "plugins" in CN-Infra lingo, where each plugin provides a very specific/focused functionality. Some plugins are provided by the CN-Infra framework itself, some are written by the app's implementors. In other words, the CN-Infra framework itself is implemented as a set of plugins that together provide the framework's functionality, such as logging, health checks, messaging (e.g. Kafka), a common front-end API and back-end connectivity to various KV data stores (Etcd, Cassandra, Redis, ...), and REST and gRPC APIs.

The architecture of the CN-Infra framework is shown in the following figure.

The CN-Infra framework consists of a Agent that provides plugin lifecycle management (initialization and graceful shutdown of plugins) and a set of framework plugins. Note that the figure shows not only CN-Infra plugins that are a part of the CN-Infra framework, but also app plugins that use the framework. CN-Infra framework plugins provide APIs that are consumed by app plugins. App plugins themselves may provide their own APIs consumed by external clients.

The framework is modular and extensible. Plugins supporting new functionality (e.g. another KV store or another message bus) can be easily added to the existing set of CN-Infra framework plugins. Moreover, CN-Infra based apps can be built in layers: a set of app plugins together with CN-Infra plugins can form a new framework providing APIs/services to higher layer apps. This approach was used in the VPP Agent - a management/control agent for VPP based software data planes.,

Extending the code base does not mean that all plugins end up in all apps - app writers can pick and choose only those framework plugins that 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 - handles GRPC requests and allows app plugins to define their own GRPC services
  • 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 - key-value data store adapter for Consul
  • Etcd - key-value data store adapter for Etcd
  • Redis - key-value data store adapter for Redis
  • Casssandra - key-value data store adapter for Cassandra
  • [FileDB][docs-filedb] - key-value data store using OS filesystem

• Messaging - provides a common API and connectivity to message buses:

  • Kafka - adapter for the Kafka message bus (built on top of Sarama)

• Logging:

  • Logrus wrapper - 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 - 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 - allows to monitor the status of plugins and exposes it via HTTP
  • Probe - callable remotely from K8s

• Miscellaneous - value-add plugins supporting the operation of a CN-Infra based application:

  • Config - helpers for loading plugin configuration.
  • Datasync - provides data resynchronization after HA events (restart or connectivity restoration after an outage) for data stores, gRPC and REST.
  • IDX Map - reusable thread-safe map with advanced features:
    • multiple subscribers for watching changes in the map
    • secondary indexes
  • ServiceLabel - 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.