Model

Model Spec

• describes model using:
  • module (for grouping models)
  • version (for versioning value)
  • type (for recognizing kind)

Model Instance

described by proto.Message (Model)

• may have attributes defined

  • these could be derived from actual config or runtime state

• instance data is organized into 3 types:

  • Config
  • State
  • Metrics

Config

• Intended Config (specific proto.Message registered with model)
  • defined by NB, read-only by agent
  • in KVDB stored under key config/<PREFIX>/<NAME>
• Custom Metadata (map[string][]interface{})
  • defined by NB, used to organize and categorize objects
  • in KVDB stored as proto extension inside value for intended config

State

• Instance Status (enum InstanceStatus)
  • each resource instance must have status defined
  • determined by scheduler during transactions
• Actual Config (specific proto.Message registered with model)
  • from SB when updated by Retrieve
  • or by scheduler (using NB data) after successful Create/Update/Delete (this can optionally be avoided if we call Retrieve after any change)
  • in KVDB stored under key status/<PREFIX>/<NAME> as field
• Runtime State (specific proto.Message? or common RuntimeState)
  • from SB, updated by CRUD
  • or via SB notifications

Metrics

• Collected Stats (CollectedStats)
  • statistics collected from SB

Data Operations

Operation	Upstream	Downstream	Description	Purpose
Active Models	reads	determines	supported model types	list of model specs for supported models
Model Configuration	writes/reads	-	desired model config	defined from upstream, consumed by Agent
Custom Annotations	writes/reads	-	user-defined metadata	optional annotations attached to models
Configuration Status	reads	-	status of known config	updated by Agent on any status changes in config
Running Configuration	reads	syncs	actual config in SB	represents last known downstream state
Index Data	reads	syncs	indexes for config	used for referencing names and indexes
Collected Metrics	reads	publishes	statistics data from SB	various collected counters and stats

Actual Support

NB access	Etcd (KVDB)	gRPC	KVScheduler
Write desired config (NB)	✔	✔	✔
Read desired config (NB)	✔	✘	✔
Read/Write custom labels (NB)	✘	✘	✘
Get config state (NB->SB)	✘ (some state is stored under /state/)	✘	✔
Dump running config (SB)	✘	✔ (direct SB access)	✔
Export running metrics (SB)	✔ (partly exported by some models)	✘	✘

Known Limitations

• developers need to modify code in several places when adding new features
  • clientv1 code duplication
• extending NB API requires painful wrapping of existing client packages
  • used for adding custom functionality (e.g. custom VPP plugins, custom SB plugin..)
• NB API for gRPC (rpc.proto) contains huge proto message with supported models
  • needs to be updated
  • does not allow extensibility
• gRPC has no way to support reading of model data (beside direct VPP dump which does not go through KVScheduler)
• the status of the models (configured/pending/error/..) is not kept in place that provides universal access from NB API
• using keys for referencing models does not make much sense for gRPC, the model contains all data required to build the key
  • prefix from type of proto message
  • name from model data
• resync/change behavior is currently confusing newcomers
  • it can also cause some unrelated errors to appear (registration of memif socket with 0 ID)

Required Functionality

• gRPC API
  • write NB configuration
    • the response should contain config status (ok/pending/error) for configured models
  • read NB configuration
    • this should include last config status for all models
  • dump SB configuration (directly from SB)

Goals

• there should be single common way to configure via NB, that uses generic API that is abstracted from specific model types
• each model type should register some kind of model specification to central place to allow universal generation of model keys
• resync should just be an option for writing(setting) configuration, since it does not differ from change that much
• it should be possible to define new type of interface outside of interface plugin
• interface plugin should be mandatory for both Linux/vpp

Proposal

Introducing Model type that can wrap any protobuf message along with model key in generic Model definition.

Model

• represents supported northbound data model
• models package defines protobuf definition for model, generalizing any specifics of data in some model

Model Spec

Key

• composed of several parts (e.g. vpp/config/v1/interfaces/memif1)
  • vpp module?? (group of models)
  • config model data class (config, status, error, ?)
  • v1 model version
  • interfaces model type
  • memif1 model instance label

Value

• proto message marshalled to any field
• wrapping it with any provides decoupling of key and model, and not needing for classification

Module

• module represents group of models (e.g. vpp, Linux)
• all support modules can be listed from NB

Instance data

• represents single model instance
• all models configured from NB have configuration state

Configuration State

• Configured - successfully configured on SB
• Pending - dependency is missing (e.g. interface does not exist)
• Failed - configuration failed (e.g. SB returned error)
• Discovered - discovered on southband (needed?? better name???) (this probably won't be needed)
• Invalid - invalid configuration data (scrambled, incomplete)

Configuration

• read-only from SB
• synchonizes (update or remove) desired configuration
• can retrieve (current) desired configuration
• response represents actual configuration status for specific item

Set request vpp/config/v1/xxx:

• model data

Get response vpp/config-state/v1/xxx:

• previously set model data
• configuration status (in get only)
• if status=failed: error(s)
• if status=pending: model id(s) of dependencies
• if status=configured: none?

Status

• read-only from NB
• contains all dumped data including data with origin=SB

Response - vpp/status/v1/xxx:

• model data (should be almost equal to the one at config)
• extra metadata (all extra info from southband, e.g. swIfIdx, ..)