manuals/developers-guide/src/main/asciidoc/core/config.adoc

   1 == Configuring the OpenDaylight controller\r
   2 \r
   3 The common way to configure applications is to use configuration files such as xml or properties files. Although such files are easy for use in small scale applications, they offer limiterd capabilities in the case of fast growing and multi-module applications. Static config files become vast, non-transparent, and inconsistent. For highly dynamic and long living environments, proper configuration is an essential requirement. The OSGi framework provides configuration service (Config Admin), and allows runtime module configuration. However, it still lacks a validation process. A new module configuration can negatively affect other modules. It also does not solve problems relating to the atomicity of the change.\r
   4 \r
   5 === Terms used in this section\r
   6 \r
   7 * *Module*: A compact part of a system, whose configuration is managed by the configuration subsystem.\r
   8 \r
   9 * *Module factory*: Important for creating module instances. Module factories are uniquely identified by name.\r
  10 \r
  11 \r
  12 * *Service*: Public API, which is used to access module instances, similar to interface in Java. Any module can implement or provide multiple services.\r
  13 \r
  14 \r
  15 * *Configuration*: Application state represented by modules definition, properties, and relations amongst them.\r
  16 \r
  17 === Config component maps\r
  18 \r
  19 .Load balancer REST APIs summary\r
  20 \r
  21 [cols="3*", options="header"]\r
  22 \r
  23 |===\r
  24 \r
  25 |Artefact ID  |Component   |Description\r
  26 \r
  27 |config-api +\r
  28 \r
  29 config-manager +\r
  30 \r
  31 config-util\r
  32 \r
  33 |config-subsystem-core\r
  34 \r
  35 |Config subsystem core. Manages the configuration of the controller.\r
  36 Responsibilities include scanning of bundles for ModuleFactories, transactional management of lifecycle and dependency injection for config modules, and exposure of modules and their configuration into JMX.\r
  37 \r
  38 \r
  39 |netty-config-api +\r
  40 \r
  41 netty-timer-config +\r
  42 \r
  43 netty-threadgroup-config +\r
  44 \r
  45 netty-event-executor-config\r
  46 \r
  47 |netty-config\r
  48 \r
  49 |Config modules for netty related resources e.g. netty-threadgroup, netty-timer etc. \r
  50 Contains config module definition in form of yang schemas and generated code binding for config subsystem.\r
  51 \r
  52 \r
  53 |shutdown-api +\r
  54 \r
  55 shutdown-impl\r
  56 \r
  57 |controller-shutdown\r
  58 \r
  59 |Controller shutdown mechanism. Brings down the whole OSGi container of the controller. Authorization required in form of a *secret string*. Also contains config module definition in form of yang schemas and generated code binding for config subsystem. This makes it possible to invoke shutdown using config-sbusystem\r
  60 \r
  61 \r
  62 \r
  63 \r
  64 |threadpool-config-api +\r
  65 \r
  66 threadpool-config-impl\r
  67 \r
  68 |threadpool-config\r
  69 \r
  70 |Config modules for threading related resources such as threadfactories and fixed-threadpool. \r
  71 Contains config module definition in the form of yang schemas and generated code binding for config subsystem.\r
  72 \r
  73 \r
  74 \r
  75 |logback-config\r
  76 \r
  77 |logback-config\r
  78 \r
  79 |Config modules for logging(logback) related resources such as loggers and appenders. \r
  80 Contains config module definition in the form of yang schemas and generated code binding for config subsystem.\r
  81 \r
  82 \r
  83 \r
  84 |netconf-config-dispatcher\r
  85 \r
  86 |netconf-config-dispatcher-config\r
  87 \r
  88 |Config modules for netconf-dispatcher(from netconf subsystem). \r
  89 Contains config module definition in form of yang schemas and generated code binding for config subsystem.\r
  90 \r
  91 \r
  92 |yang-jmx-generator +\r
  93 \r
  94 yang-jmx-generator-plugin\r
  95 \r
  96 |yang-jmx-config-generator\r
  97 \r
  98 |Maven plugin that generates the config subsystem code binding from provided yang schemas. This binding is required when bundles want to participate in the config subsystem.\r
  99 \r
 100 \r
 101 \r
 102 \r
 103 |yang-test +\r
 104 \r
 105 yang-test-plugin\r
 106 \r
 107 |yang-jmx-config-generator-testing-modules\r
 108 \r
 109 |Testing resources for the maven plugin.\r
 110 \r
 111 \r
 112 |config-persister-api +\r
 113 \r
 114 config-persister-file-xml-adapter +\r
 115 \r
 116 config-persister-directory-xml-adapter\r
 117 \r
 118 \r
 119 |config-persister\r
 120 \r
 121 |Contains api definition for an extensible configuration persister(database for controller configuration). The persister (re)stores the configuration for the controller. Persister implementation can be found in the netconf subsystem. The adapter bundles contain concrete implementations of storage extension. They store the config as xml files on filesystem.\r
 122 \r
 123 |config-module-archetype\r
 124 \r
 125 |config-module-archetype\r
 126 \r
 127 |Maven archetype for *config subsystem aware* bundles. This archetype contains blueprints for yang-schemas, java classes and other files(e.g. pom.xml) required for a bundle to participate in the config subsystem. This archetype generates a bundle skeleton that can be developed into a full blown *config subsystem aware* bundle.\r
 128 \r
 129 \r
 130 |===\r
 131 \r
 132 === Configuration and transactional processes for the OpenDaylight controller\r
 133 \r
 134 The Configuration operation has three stages:\r
 135 \r
 136 . A proposed configuration is created. Its target is to replace the old configuration.\r
 137 \r
 138 .  The proposed configuration must be validated before it can be committed. If it passes validation successfully, the proposed state of the configuration is changed to validated. \r
 139 \r
 140 .  A validated configuration can be committed and the affected modules can be reconfigured. \r
 141 \r
 142 In fact, each configuration operation is wrapped in a transaction. Once a transaction is created, it can be configured. A user can abort the transaction during this stage. After the transaction configuration is done, it is committed to the validation stage. In this stage, the validation procedures are invoked. If one or more validations fail, the transaction can be reconfigured. On success, the second phase commit is invoked. If this commit is successful, the transaction enters the last stage known as committed. After that, the required modules are reconfigured. If the second phase commit fails, it means that the transaction is unhealthy. Basically, a new configuration instance creation failed, and the application can be in an inconsistent state.\r
 143 \r
 144 image::configuration.jpg[title="Configuration stage", alt="Configuration stage"]\r
 145 \r
 146 image::Transaction.jpg[title="Transaction stage", alt="Transaction stage"]\r
 147 \r
 148 \r
 149 To secure the consistency and safety of a new configuration, and to avoid conflicts, the configuration validation process is necessary. Usually, validation checks the input parameters of a new configuration and  verifies module-specific relationships. The validation procedure results in a decision indicating whether the proposed configuration is healthy.\r
 150 \r
 151 Since there can be dependencies between modules, a change of a module configuration can affect the state of other modules. Therefore, we need to verify whether dependencies on other modules can be resolved. The dependency resolver acts similar to dependency injectors. A dependency tree is built.\r
 152 \r
 153 === SPIs\r
 154 \r
 155 Module org.opendaylight.controller.config.spi.Module is a common interface for all modules. Every module must implement it. The module is designated to hold configuration attributes, validate them, and create an instance of service based on the attributes. This instance must implement AutoCloseable interface, owing to resources clean up. If the module was created from an already running instance, it contains an old instance of the module. The module can implement multiple services. If the module depends on other modules, setters need to be annotated with @RequireInterface.\r
 156 \r
 157 In creating the module, firstly, the module needs to be configured, be set with all required attributes. Thereafter, the module is moved to the commit stage, where validation is performed. If it fails, the module attributes can be reconfigured. Otherwise, a new instance is created or an old instance is reconfigured. A module instance is identified by ModuleIdentifier which consists of the factory name and instance name.\r
 158 \r
 159 \r
 160 ModuleFactory org.opendaylight.controller.config.spi.ModuleFactory interface must be implemented by each module factory. The module factory can create new module instance in two ways: from an existing module instance or a pure new instance. Also, it can return default modules, useful for populating registry with an already existing configuration. A module factory implementation must have a globally unique name.\r
 161 \r
 162 === APIs\r
 163 \r
 164 * *ConfigRegistry*: Represents functionality provided by configuration transaction (create, destroy module, validate, abort transaction).\r
 165 \r
 166 \r
 167 * *ConfigTransactionController?*: Represents functionality for manipulating configuration transactions (begin, commit config ).\r
 168 \r
 169 \r
 170 * *RuntimeBeanRegistratorAwareConfiBean*: The module implementing this interface will recieve RuntimeBeanRegistrator before getInstance is invoked.\r
 171 \r
 172 === Runtime APIs\r
 173 \r
 174 * *RuntimeBean*: The common interface for all runtime beans.\r
 175 \r
 176 * *RootRuntimeBeanRegistrator*: Represents functionality for the root runtime bean registration, which subsequently allows hierarchical registrations.\r
 177 \r
 178 * *HierarchicalRuntimeBeanRegistration*: Represents functionality for the runtime bean registration and unreregistration from hierarchy.\r
 179 \r
 180 * *JMX APIs*: JMX API is purposed as a transition between Client API and JMX platform.\r
 181 \r
 182 * *ConfigTransactionControllerMXBean*: Extends ConfigTransactionController, executed by Jolokia clients on configuration transaction.\r
 183 \r
 184 * *ConfigRegistryMXBean*: Represents the entry point of configuration management for MXBeans.\r
 185 \r
 186 NOTE: The Object Name is the pattern used in JMX to locate JMX beans. It consists of domain and key properties (at least one key-value pair). Domain is defined as "org.opendaylight.controller". The only mandatory property is "type".\r
 187 \r
 188 === Use case scenarios\r
 189 \r
 190 The list provides a few samples of successful and unsuccessful transactions scenarios.\r
 191 \r
 192 ==== Successful commit scenario\r
 193 \r
 194 . The user creates a transaction calling creteTransaction() method on ConfigRegistry.\r
 195 \r
 196 . The ConfigRegisty creates a transaction controller and registers the transaction as a new bean.\r
 197 \r
 198 \r
 199 . Runtime configurations are copied to the transaction. The user can create modules, and set their attributes.\r
 200 \r
 201 \r
 202 . The configuration transaction is committed.\r
 203 \r
 204 \r
 205 . The validation process is performed.\r
 206 \r
 207 \r
 208 . After successful validation, the second phase commit begins.\r
 209 \r
 210 \r
 211 . Modules proposed to be destroyed are destroyed, their service instances are closed.\r
 212 \r
 213 \r
 214 . The Runtime beans are set to registrator.\r
 215 \r
 216 \r
 217 . The transaction controller invokes the method getInstance on each module.\r
 218 \r
 219 \r
 220 . The transaction is committed and resources are closed or released.\r
 221 \r
 222 \r
 223 \r
 224 ==== Validation failure scenario\r
 225 \r
 226 The transaction is the same as previous case until the validation step.\r
 227 \r
 228 . The user creates a transaction calling creteTransaction() method on ConfigRegistry.\r
 229 \r
 230 . The ConfigRegisty creates a transaction controller and registers the transaction as a new bean.\r
 231 \r
 232 \r
 233 . Runtime configurations are copied to the transaction. The user can create modules, and set their attributes.\r
 234 \r
 235 \r
 236 . The configuration transaction is committed.\r
 237 \r
 238 \r
 239 . The validation process is performed.\r
 240 \r
 241 \r
 242 . If validation fails such as illegal input attributes values or dependency resolver failure, ValidationException is thrown and exposed to the user.\r
 243 \r
 244 . The user can decide to reconfigure the transaction, commit again, or abort current transaction.\r
 245 \r
 246 \r
 247 . On aborted transactions, TransactionController and JMXRegistrator are properly closed.\r
 248 \r
 249 \r
 250 . The Unregistration event is sent to ConfigRegistry.\r
 251 \r
 252 === Default module instances\r
 253 \r
 254 The configuration subsystem provides a way for modules to create default instances. Default instance is an instance of a module that is created at the module bundle startup (module becomes visible for configuration subsystem for example, its bundle is activated in OSGi environment). By default, no default instances are produced.\r
 255 \r
 256 \r
 257 The default instance does not differ from instances created later in the module lifecycle. The only difference is that the configuration for the default instance cannot be provided by the configuration subsystem. The module has to acquire the configuration for these instances on its own, and it can be acquired from, for example, environment variables. After the creation of a default instance, it acts as a regular instance, and fully participates in the configuration subsystem (It can be reconfigured or deleted in following transactions.).\r
 258 \r