docs/design/netconf-connector-clustering.adoc

   1 = NETCONF Connector Clustering
   2 Tony Tkacik <ttkacik@cisco.com>;Maros Marsalek <mmarsale@cisco.com>; Tomas Cere <tcere@cisco.com>
   3
   4 == Terminology
   5
   6 Entity Ownership Service :: Simplified RAFT service with
   7 YANG Instance-Identifier based namespace for registering ownership of logical
   8 entity. Such entity may be topology instance or node instance.
   9
  10 Peer ::
  11 Instance of same logical component managing same logical state. Peer may
  12 be running in different JVM process.
  13
  14 Master::
  15 Peer which is responsible for coordinating other peers,
  16 publishing services and state for other applications to consume.
  17
  18 Slave::
  19 Peer which reports its state changes to master and may process some of the
  20 workload.
  21
  22 Topology Manager ::
  23 Component responsible for managing topology-wide operations and managing lifecycle
  24 of Node Managers
  25
  26 Node Manager ::
  27 Component responsible for managing node specific context.
  28 Node Manager is expected to manages only one node in topology.
  29
  30 Controller-initiated connection :: Connection to managed extenal system which is
  31 initiated by application (in extension external trigger to controller
  32   such as configuration change).
  33
  34 External System-initiated connection :: Connection to controller which is
  35   initiated by external system (e.g. Openflow switch, PCC).
  36
  37 NETCONF Call-Home :: Use-case where NETCONF server initiates connection to client,
  38 the connection initiation is inversed as is standard NETCONF protocol.
  39 It is NETCONF specific case of External System-initiated connection.
  40
  41 NOTE: Manager suffix may change if it is required on review, other
  42 name candidates are Administrator , Supervisor, Controller, Context
  43
  44
  45 == Basic Concepts
  46
  47 IMPORTANT:
  48 This document references and considers functionality which is not
  49 implemented yet, which is not part of Beryllium delivery and may be delivered
  50 in subsequent releases.
  51 +
  52 Some design details are not yet specified, which allows for more fine-tuning
  53 of design or to allow for new feature set.
  54
  55 NETCONF Clustering model (and by extensions Topology-based protocol clustering model)
  56 is built on top of Actor supervision and  Actor hierarchy patterns,
  57 which allows us to model relationship between components similar to data hierarchy
  58 in topology model.
  59
  60 [plantuml]
  61 ....
  62
  63 interface Peer<T> {
  64   + getPeers() : Collection<PeerReference<T>>
  65 }
  66
  67 interface TopologyManager extends Peer {
  68   + publishState(Node)
  69   + removeNode(NodeId)
  70   + createNodeManager(Node) : NodeManager
  71 }
  72
  73 interface NodeManager extends Peer {
  74   + publishState(Node)
  75 }
  76
  77 TopologyManager -> NodeManager : manages
  78 ....
  79
  80 === Topology Manager ===
  81
  82 *Topology Manager* is component with multiple instances
  83  in cluster, logically grouped into peer groups which manages one NETCONF topology.
  84
  85 It is responsible for:
  86
  87 - *Coordination with logical peers* (other instances of same Topology Manager):
  88 ** participate on Master / Slave elections for logical peer group.
  89 ** publishing / consuming application specific state among peers.
  90
  91 - *management of local (child) Node Manager instances* for particular
  92   topology node:
  93 ** creation of local Node Managers when needed
  94 ** managing their lifecycle based on application logic.
  95
  96
  97 - If instance is Master of logical peer group:
  98 ** Request creation of Node Manager for particular topology node
  99    on peer Topology Managers.
 100 ** Assigning roles to concrete instances of Node Manager in
 101    Node Manager peer group (usually master-slave election, but multimaster
 102    may be also possible).
 103 ** delegating write access to topology node in question to master Node Manager
 104    for particular node.
 105 ** allows Node Managers based on their role to publish state / functionality
 106    for node in question.
 107
 108 ==== Use-case specific behaviour ====
 109
 110 - *Controller-initiated connections* (Normal NETCONF behaviour)
 111 ** Master listens on configuration NETCONF topology
 112    and communicates node addition / change / removal to peers and schedules
 113    * requests creation of Node Managers on peers
 114 - *External-system initiated connections:* (NETCONF Call-Home)
 115 ** Topology Manager which received incoming connection is responsible to
 116    propagate incoming connection state updates to it peers add to create
 117    Node Manager for incoming connection.
 118 ** Topology Manager assign logical cluster-wide roles based on protocol
 119    semantic to all Node Manager instances for same logical node.
 120
 121 === Node Manager ===
 122
 123 *Node Manager* is component with multiple instances in cluster, logically
 124 grouped into peer groups which manages one NETCONF topology node respectively.
 125
 126 It is responsible for:
 127
 128 - *Coordination with parent Topology Manager*
 129 ** publishing state changes to parent Topology Manager.
 130
 131 - *Coordination with logical peers*
 132 ** important state updates with logical peers based on application logic.
 133
 134 == Scope of implementation
 135 === Beryllium scope of NETCONF Clustering
 136
 137 - Implementation of logic as described above using *Akka Actor* system
 138   and *Entity Ownership Service* to determine Master-Slave relationship for
 139   Topology Manager and Node Manager instances.
 140
 141 - Only support for *Controller-initiated connection* use-case based on NETCONF
 142   Topology Configuration model.
 143
 144 - *No planned support* of clustering of NETCONF devices configured by Helium
 145   and Lithium style of configuration - *using config subsystem*.
 146 - *No support* of  clustering for *controller-config* NETCONF device, since it represents
 147   loop to instance, which on each node in cluster represents different
 148
 149
 150 === Possible future work-items
 151
 152 IMPORTANT: Following items are not required to fulfill Beryllium NETCONF Clustering.
 153
 154 - Extend framework to support *External system-initiated connections*
 155 - Abstract out NETCONF-specific details from described clustering framework
 156   to allow for reusability for other "topology-based" applications.
 157 - Abstract out core framework to provide same functionality for non-topology
 158   based applications.
 159
 160 == Design
 161
 162 SPI & Base messages for NETCONF Connector Clustering are described and
 163 proposed in Java API form in Gerrit:
 164   https://git.opendaylight.org/gerrit/#/c/26728/8
 165
 166
 167 === Multiple transport backends
 168
 169 Solution was designed in mind to allow for multiple implementation of cluster-wide
 170 communication between Topology Managers and Node Managers
 171 to allow easier porting to other transport solutions.
 172
 173 [plantuml]
 174 ....
 175 component "Netconf Connector" as netconf.connector
 176
 177 interface "Abstract Topology API" as topo.api
 178 interface "Mount Point API" as mount.api
 179
 180 component "Common Topology Backend" as topo.common
 181 component "Beryllium Topology Backend" as topo.actor
 182 component "Lithium Topology Backend" as topo.rpc
 183
 184 interface "Entity Ownership API" as entity.api
 185
 186 netconf.connector --> topo.api : uses
 187 netconf.connector --> mount.api : uses
 188
 189 topo.api -- topo.actor
 190 topo.api -- topo.rpc
 191
 192 topo.common --> entity.api
 193 topo.actor --> topo.common
 194 topo.rpc --> topo.common
 195 ....
 196
 197 === Connecting a NETCONF device
 198
 199 [plantuml]
 200 ....
 201 actor User
 202 participant Topology as topo.master <<(M,#ADD1B2)>>
 203 participant Topology  as topo.slave <<(S,#FF7700)>>
 204 participant "MD SAL" as ds.cfg <<(C,#ADD1B2)>>
 205 participant "Oper DS" as ds.oper <<(C,#ADD1B2)>>
 206 autonumber
 207 topo.master -> EntityOwnershipService : registerCandidate(/topology/netconf)
 208 topo.slave -> EntityOwnershipService : registerCandidate(/topology/netconf)
 209 activate topo.master
 210 topo.master <-- EntityOwnershipService : ownershipChanged(isOwner=true)
 211 topo.slave <-- EntityOwnershipService : ownershipChanged(isOwner=false)
 212
 213 topo.master -> ds.cfg : registerDataTreeChangeListener(/topology/netconf)
 214 deactivate topo.master
 215 User -> ds.cfg : create(/topology/netconf/node)
 216 activate topo.master
 217 ds.cfg -> topo.master : created(/topology/netconf/node)
 218 participant Node as node.master <<(M,#ADD1B2)>>
 219 participant Node as node.slave <<(S,#FF7700)>>
 220
 221 topo.master -> topo.slave : connect(node)
 222 activate topo.slave
 223 create node.master
 224 topo.slave -> node.master : create(node)
 225 deactivate topo.slave
 226 topo.master -> topo.master : connect(node)
 227 activate topo.master
 228 create node.slave
 229 topo.master -> node.slave : create(node)
 230 deactivate topo.master
 231 deactivate topo.master
 232
 233 node.master -> EntityOwnershipService : registerCandidate(/topology/netconf/node)
 234 node.slave -> EntityOwnershipService : registerCandidate(/topology/netconf/node)
 235
 236 node.slave -> topo.master : updateStatus(connecting)
 237 node.master -> topo.slave : updateStatus(connecting)
 238 topo.slave -> topo.master : updateStatus(connecting)
 239
 240 node.slave <-- EntityOwnershipService : ownershipChanged(isOwner=false)
 241
 242 activate node.master
 243 node.master <-- EntityOwnershipService : ownershipChanged(isOwner=true)
 244
 245 node.master -> node.master : createMountpoint()
 246 node.master -> MountPointService : registerMountpoint(/topology/netconf/node)
 247 activate topo.slave
 248 node.master --> topo.slave : updateStatus(published)
 249 deactivate node.master
 250 topo.slave --> topo.master : updateStatus(published)
 251 deactivate topo.slave
 252
 253 ....
 254
 255 === Schema resolution
 256
 257 [plantuml]
 258 ....
 259 participant Node as node.master <<(M,#ADD1B2)>>
 260 participant Schema as schema.master <<(M,#ADD1B2)>>
 261 participant Node as node.slave <<(S,#FF7700)>>
 262 participant Schema as schema.slave <<(S,#FF7700)>>
 263 participant Device as device
 264 autonumber
 265 node.master -> node.master : createMountpoint()
 266 node.master -> schema.master : setupSchema()
 267 schema.master -> device : downloadSchemas()
 268 schema.master --> node.master : remoteSchemaContext()
 269 node.master -> MountPointService : registerMountpoint(/topology/netconf/node)
 270
 271 node.master -> node.slave : announceMasterMountPoint()
 272 node.slave -> schema.slave : resolveSlaveSchema()
 273 schema.slave -> schema.master : getProvidedSources()
 274 schema.slave -> schema.slave : registerProvidedSources()
 275 node.slave -> MountPointService : registerProxyMountpoint(/topology/netconf/node)
 276 ....