docs/developer-guide/distribution-version.rst

   1 Distribution Version reporting
   2 ==============================
   3
   4 Overview
   5 --------
   6
   7 This section provides an overview of **odl-distribution-version** feature.
   8
   9 A remote user of OpenDaylight usually has access to RESTCONF and NETCONF
  10 northbound interfaces, but does not have access to the system
  11 OpenDaylight is running on. OpenDaylight has released multiple versions
  12 including Service Releases, and there are incompatible changes between them.
  13 In order to know which YANG modules to use, which bugs to expect
  14 and which workarounds to apply, such user would need to know the exact version
  15 of at least one OpenDaylight component.
  16
  17 There are indirect ways to deduce such version, but the direct way is enabled
  18 by odl-distribution-version feature. Administrator can specify version strings,
  19 which would be available to users via NETCONF, or via RESTCONF
  20 if OpenDaylight is configured to initiate NETCONF connection
  21 to its config subsystem northbound interface.
  22
  23 By default, users have write access to config subsystem,
  24 so they can add, modify or delete any version strings present there.
  25 Admins can only influence whether the feature is installed, and initial values.
  26
  27 Config subsystem is local only, not cluster aware,
  28 so each member reports versions independently. This is suitable for heterogeneous clusters.
  29 On homogeneous clusters, make sure you set and check every member.
  30
  31 Key APIs and Interfaces
  32 -----------------------
  33
  34 Current implementation relies heavily on ``config-parent`` parent POM file from Controller project.
  35
  36 YANG model for config subsystem
  37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38
  39 Throughout this chapter, *model* denotes YANG module, and *module* denotes item
  40 in config subsystem module list.
  41
  42 Version functionality relies on config subsystem and its ``config`` YANG model.
  43 The YANG model ``odl-distribution-version`` adds an identity ``odl-version``
  44 and augments ``/config:modules/module/configuration`` adding new case for ``odl-version`` type.
  45 This case contains single leaf ``version``, which would hold the version string.
  46
  47 Config subsystem can hold multiple modules, the version string should contain
  48 version of OpenDaylight component corresponding to the module name.
  49 As this is pure metadata with no consequence on OpenDaylight behavior,
  50 there is no prescribed scheme for chosing config module names.
  51 But see the default configuration file for examples.
  52
  53 Java API
  54 ~~~~~~~~
  55
  56 Each config module needs to come with java classes which override ``customValidation()``
  57 and ``createInstance()``. Version related modules have no impact on OpenDaylight internal behavior,
  58 so the methods return void and dummy closeable respectively, without any side effect.
  59
  60 Default config file
  61 ~~~~~~~~~~~~~~~~~~~
  62
  63 Initial version values are set via config file ``odl-version.xml`` which is created in
  64 ``$KARAF_HOME/etc/opendaylight/karaf/`` upon installation of ``odl-distribution-version`` feature.
  65 If admin wants to use different content, the file with desired content has to be created
  66 there before feature installation happens.
  67
  68 By default, the config file defines two config modules, named ``odl-distribution-version``
  69 and ``odl-odlparent-version``.
  70
  71 Currently the default version values are set to Maven property strings
  72 (as opposed to valid values), as the needed new functionality did not make it
  73 into Controller project in Boron. See Bug number 6003.
  74
  75 Karaf Feature
  76 ~~~~~~~~~~~~~
  77
  78 The ``odl-distribution-version`` feature is currently the only feature defined
  79 in feature repository of artifactId ``features-distribution``,
  80 which is available (transitively) in OpenDaylight Karaf distribution.
  81
  82 RESTCONF usage
  83 ~~~~~~~~~~~~~~
  84
  85 Opendaylight config subsystem NETCONF northbound is not made available just by installing
  86 ``odl-distribution-version``, but most other feature installations would enable it.
  87 RESTCONF interfaces are enabled by installing ``odl-restconf`` feature,
  88 but that do not allow access to config subsystem by itself.
  89
  90 On single node deployments, installation of ``odl-netconf-connector-ssh`` is recommended,
  91 which would configure ``controller-config`` device and its MD-SAL mount point.
  92 See documentation for clustering on how to create similar devices for member modes,
  93 as ``controller-config`` name is not unique in that context.
  94
  95 Assuming single node deployment and user located on the same system,
  96 here is an example ``curl`` command accessing ``odl-odlparent-version`` config module:
  97
  98 .. code:: bash
  99
 100     curl 127.0.0.1:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-distribution-version:odl-version/odl-odlparent-version
 101