docs/03-Functional_Requirements.rst

   1 Functional Requirements
   2 -----------------------
   3
   4 Basic Actions
   5 ~~~~~~~~~~~~~
   6
   7 This section describes the basic functions may required by Escalator.
   8
   9 Preparation (offline)
  10 ^^^^^^^^^^^^^^^^^^^^^
  11
  12 This is the design phase when the upgrade plan (or upgrade campaign) is
  13 being designed so that it can be executed automatically with minimal
  14 service outage. It may include the following work:
  15
  16 1. Check the dependencies of the software modules and their impact,
  17    backward compatibilities to figure out the appropriate upgrade method
  18    and ordering.
  19 2. Find out if a rolling upgrade could be planned with several rolling
  20    steps to avoid any service outage due to the upgrade some
  21    parts/services at the same time.
  22 3. Collect the proper version files and check the integration for
  23    upgrading.
  24 4. The preparation step should produce an output (i.e. upgrade
  25    campaign/plan), which is executable automatically in an NFV Framework
  26    and which can be validated before execution.
  27
  28    -  The upgrade campaign should not be referring to scalable entities
  29       directly, but allow for adaptation to the system configuration and
  30       state at any given moment.
  31    -  The upgrade campaign should describe the ordering of the upgrade
  32       of different entities so that dependencies, redundancies can be
  33       maintained during the upgrade execution
  34    -  The upgrade campaign should provide information about the
  35       applicable recovery procedures and their ordering.
  36    -  The upgrade campaign should consider information about the
  37       verification/testing procedures to be performed during the upgrade
  38       so that upgrade failures can be detected as soon as possible and
  39       the appropriate recovery procedure can be identified and applied.
  40    -  The upgrade campaign should provide information on the expected
  41       execution time so that hanging execution can be identified
  42    -  The upgrade campaign should indicate any point in the upgrade when
  43       coordination with the users (VNFs) is required.
  44
  45 .. <hujie> Depends on the attributes of the object being upgraded, the
  46   upgrade plan may be slitted into step(s) and/or sub-plan(s), and even
  47   more small sub-plans in design phase. The plan(s) or sub-plan(s) my
  48   include step(s) or sub-plan(s).
  49
  50 Validation the upgrade plan / Checking the pre-requisites of System( offline / online)
  51 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  52
  53 The upgrade plan should be validated before the execution by testing
  54 it in a test environment which is similar to the product environment.
  55
  56 .. <MT> However it could also mean that we can identify some properties
  57   that it should satisfy e.g. what operations can or cannot be executed
  58   simultaneously like never take out two VMs of the same VNF.
  59
  60 .. <MT> Another question is if it requires that the system is in a particular
  61   state when the upgrade is applied. I.e. if there's certain amount of
  62   redundancy in the system, migration is enabled for VMs, when the NFVI
  63   is upgraded the VIM is healthy, when the VIM is upgraded the NFVI is
  64   healthy, etc.
  65
  66 .. <MT> I'm not sure what online validation means: Is it the validation of the
  67   upgrade plan/campaign or the validation of the system that it is in a
  68   state that the upgrade can be performed without too much risk?==
  69
  70 Before the upgrade plan being executed, the system healthy of the
  71 online product environment should be checked and confirmed to satisfy
  72 the requirements which were described in the upgrade plan. The
  73 sysinfo, e.g. which included system alarms, performance statistics and
  74 diagnostic logs, will be collected and analogized. It is required to
  75 resolve all of the system faults or exclude the unhealthy part before
  76 executing the upgrade plan.
  77
  78
  79 Backup/Snapshot (online)
  80 ^^^^^^^^^^^^^^^^^^^^^^^^
  81
  82 For avoid loss of data when a unsuccessful upgrade was encountered, the
  83 data should be back-upped and the system state snapshot should be taken
  84 before the execution of upgrade plan. This would be considered in the
  85 upgrade plan.
  86
  87 Several backups/Snapshots may be generated and stored before the single
  88 steps of changes. The following data/files are required to be
  89 considered:
  90
  91 1. running version files for each node.
  92 2. system components' configuration file and database.
  93 3. image and storage, if it is necessary.
  94
  95 .. <MT> Does 3 imply VNF image and storage? I.e. VNF state and data?==
  96
  97 .. <hujie> The following text is derived from previous "4. Negotiate
  98   with the VNF if it's ready for the upgrade"
  99
 100 Although the upper layer, which include VNFs and VNFMs, is out of the
 101 scope of Escalator, but it is still recommended to let it ready for a
 102 smooth system upgrade. The escalator could not guarantee the safe of
 103 VNFs. The upper layer should have some safe guard mechanism in design,
 104 and ready for avoiding failure in system upgrade.
 105
 106 Execution (online)
 107 ^^^^^^^^^^^^^^^^^^
 108
 109 The execution of upgrade plan should be a dynamical procedure which is
 110   controlled by Escalator.
 111
 112 .. <hujie> Revised text to be general.==
 113
 114 1. It is required to supporting execution ether in sequence or in
 115    parallel.
 116 2. It is required to check the result of the execution and take the
 117    action according the situation and the policies in the upgrade plan.
 118 3. It is required to execute properly on various configurations of
 119    system object. I.e. stand-alone, HA, etc.
 120 4. It is required to execute on the designated different parts of the
 121    system. I.e. physical server, virtualized server, rack, chassis,
 122    cluster, even different geographical places.
 123
 124 Testing (online)
 125 ^^^^^^^^^^^^^^^^
 126
 127 The testing after upgrade the whole system or parts of system to make
 128 sure the upgraded system(object) is working normally.
 129
 130 .. <hujie> Revised text to be general.
 131
 132 1. It is recommended to run the prepared test cases to see if the
 133    functionalities are available without any problem.
 134 2. It is recommended to check the sysinfo, e.g. system alarms,
 135    performance statistics and diagnostic logs to see if there are any
 136    abnormal.
 137
 138 Restore/Roll-back (online)
 139 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 140
 141 When upgrade is failure unfortunately, a quick system restore or system
 142 roll-back should be taken to recovery the system and the services.
 143
 144 .. <hujie> Revised text to be general.
 145
 146 1. It is recommend to support system restore from backup when upgrade
 147    was failed.
 148 2. It is recommend to support graceful roll-back with reverse order
 149    steps if possible.
 150
 151 Monitoring (online)
 152 ^^^^^^^^^^^^^^^^^^^
 153
 154 Escalator should continually monitor the process of upgrade. It is
 155 keeping update status of each module, each node, each cluster into a
 156 status table during upgrade.
 157
 158 .. <hujie> Revised text to be general.
 159
 160 1. It is required to collect the status of every objects being upgraded
 161    and sending abnormal alarms during the upgrade.
 162 2. It is recommend to reuse the existing monitoring system, like alarm.
 163 3. It is recommend to support pro-actively query.
 164 4. It is recommend to support passively wait for notification.
 165
 166 **Two possible ways for monitoring:**
 167
 168 **Pro-Actively Query** requires NFVI/VIM provides proper API or CLI
 169 interface. If Escalator serves as a service, it should pass on these
 170 interfaces.
 171
 172 **Passively Wait for Notification** requires Escalator provides
 173 callback interface, which could be used by NFVI/VIM systems or upgrade
 174 agent to send back notification.
 175
 176 .. <hujie> I am not sure why not to subscribe the notification.
 177
 178 Logging (online)
 179 ^^^^^^^^^^^^^^^^
 180
 181 Record the information generated by escalator into log files. The log
 182 file is used for manual diagnostic of exceptions.
 183
 184 1. It is required to support logging.
 185 2. It is recommended to include time stamp, object id, action name,
 186    error code, etc.
 187
 188 Administrative Control (online)
 189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 190
 191 Administrative Control is used for control the privilege to start any
 192 escalator's actions for avoiding unauthorized operations.
 193
 194 #. It is required to support administrative control mechanism
 195 #. It is recommend to reuse the system's own secure system.
 196 #. It is required to avoid conflicts when the system's own secure system
 197    being upgraded.
 198
 199 Requirements on Object being upgraded
 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 .. <hujie> We can develop BPs in future from requirements of this section and
 203   gap analysis for upper stream projects
 204
 205 Escalator focus on smooth upgrade. In practical implementation, it
 206 might be combined with installer/deplorer, or act as an independent
 207 tool/service. In either way, it requires targeting systems(NFVI and
 208 VIM) are developed/deployed in a way that Escalator could perform
 209 upgrade on them.
 210
 211 On NFVI system, live-migration is likely used to maintain availability
 212 because OPNFV would like to make HA transparent from end user. This
 213 requires VIM system being able to put compute node into maintenance mode
 214 and then isolated from normal service. Otherwise, new NFVI instances
 215 might risk at being schedule into the upgrading node.
 216
 217 On VIM system, availability is likely achieved by redundancy. This
 218 impose less requirements on system/services being upgrade (see PVA
 219 comments in early version). However, there should be a way to put the
 220 target system into standby mode. Because starting upgrade on the
 221 master node in a cluster is likely a bad idea.
 222
 223 .. <hujie>Revised text to be general.
 224
 225 1. It is required for NFVI/VIM to support **service handover** mechanism
 226    that minimize interruption to 0.001%(i.e. 99.999% service
 227    availability). Possible implementations are live-migration, redundant
 228    deployment, etc, (Note: for VIM, interruption could be less
 229    restrictive)
 230
 231 2. It is required for NFVI/VIM to restore the early version in a efficient
 232    way, such as **snapshot**.
 233
 234 3. It is required for NFVI/VIM to **migration data** efficiently between
 235    base and upgraded system.
 236
 237 4. It is recommend for NFV/VIM's interface to support upgrade
 238    orchestration, e.g. reading/setting system state.
 239
 240