Incorporate software dimensions and other comments

Add definitions of rollback, downgrade and restore
Add rollforward and apply other comments

JIRA: ESCALATOR-24

Change-Id: I4a576c8fe1a7751ee934693ed8f948617a5542a0
Signed-off-by: Maria Toeroe <Maria.Toeroe@ericsson.com>

diff --git a/doc/02-Background_and_Terminologies.rst b/doc/02-Background_and_Terminologies.rst
index afb392f..36a81f2 100644 (file)
--- a/doc/02-Background_and_Terminologies.rst
+++ b/doc/02-Background_and_Terminologies.rst
@@ -1,4 +1,4 @@
-General Requirements Background and Terminology\r
+General Requirements Background and Terminology\r

 -----------------------------------------------\r
 \r
 Terminologies and definitions\r
 -----------------------------------------------\r
 \r
 Terminologies and definitions\r


@@ -12,7 +12,7 @@ NFVI
 VIM\r
   The term is an abbreviation for Virtual Infrastructure Management;\r
   sometimes it is also referred as control plane in this document.\r
 VIM\r
   The term is an abbreviation for Virtual Infrastructure Management;\r
   sometimes it is also referred as control plane in this document.\r

-   \r
+\r

 Operator\r
   The term refers to network service providers and Virtual Network\r
   Function (VNF) providers.\r
 Operator\r
   The term refers to network service providers and Virtual Network\r
   Function (VNF) providers.\r


@@ -25,12 +25,12 @@ Network Service
   End-users using a set of (virtualized) Network Functions\r
 \r
 Infrastructure Services\r
   End-users using a set of (virtualized) Network Functions\r
 \r
 Infrastructure Services\r

-  The term refers to services provided by the NFV Infrastructure and the \r
-  the Management & Orchestration functions to the VNFs. I.e. \r
+  The term refers to services provided by the NFV Infrastructure and the\r
+  the Management & Orchestration functions to the VNFs. I.e.\r

   these are the virtual resources as perceived by the VNFs.\r
 \r
 Smooth Upgrade\r
   these are the virtual resources as perceived by the VNFs.\r
 \r
 Smooth Upgrade\r

-  The term refers to an upgrade that results in no service outage \r
+  The term refers to an upgrade that results in no service outage\r

   for the end-users.\r
 \r
 Rolling Upgrade\r
   for the end-users.\r
 \r
 Rolling Upgrade\r


@@ -38,7 +38,7 @@ Rolling Upgrade
   a subset of nodes in a wave style rolling through the data centre. It\r
   is a popular upgrade strategy to maintain service availability.\r
 \r
   a subset of nodes in a wave style rolling through the data centre. It\r
   is a popular upgrade strategy to maintain service availability.\r
 \r

-Parallel Universe\r
+Parallel Universe Upgrade\r

   The term refers to an upgrade strategy that creates and deploys\r
   a new universe - a system with the new configuration - while the old\r
   system continues running. The state of the old system is transferred\r
   The term refers to an upgrade strategy that creates and deploys\r
   a new universe - a system with the new configuration - while the old\r
   system continues running. The state of the old system is transferred\r


@@ -59,22 +59,57 @@ Virtual Resource
   they are the resources on which VNF entities are deployed, e.g.\r
   the VMs, virtual switches, virtual routers, virtual disks etc.\r
 \r
   they are the resources on which VNF entities are deployed, e.g.\r
   the VMs, virtual switches, virtual routers, virtual disks etc.\r
 \r

-.. <MT> I don't think the VNF is the virtual resource. Virtual\r
-   resources are the VMs, virtual switches, virtual routers, virtual\r
-   disks etc. The VNF uses them, but I don't think they are equal. The\r
-   VIM doesn't manage the VNF, but it does manage virtual resources.\r
-   \r

 Visualization Facility\r
 Visualization Facility\r

-   The term refers to a resource that enables the creation\r
-   of virtual environments on top of the physical resources, e.g.\r
-   hypervisor, OpenStack, etc.\r
+  The term refers to a resource that enables the creation\r
+  of virtual environments on top of the physical resources, e.g.\r
+  hypervisor, OpenStack, etc.\r
+\r
+Upgrade Campaign\r
+  The term refers to a choreography that describes how the upgrade should\r
+  be performed in terms of its targets (i.e. upgrade objects), the\r
+  steps/actions required of upgrading each, and the coordination of these\r
+  steps so that service availability can be maintained. It is an input to an\r
+  upgrade tool (Escalator) to carry out the upgrade.\r
+\r
+Upgrade Duration\r
+  The duration of an upgrade characterized by the time elapsed between its\r
+  initiation and its completion. E.g. from the moment the execution of an\r
+  upgrade campaign has started until it has been committed. Depending on\r
+  the upgrade method and its target some parts of the system may be in a more\r
+  vulnerable state.\r
+\r
+Outage\r
+  The period of time during which a given service is not provided is referred\r
+  as the outage of that given service. If a subsystem or the entire system\r
+  does not provide any service, it is the outage of the given subsystem or the\r
+  system. Smooth upgrade means upgrade with no outage for the user plane, i.e.\r
+  no VNF should experience service outage.\r
+\r
+Rollback\r
+  The term refers to a failure handling strategy that reverts the changes\r
+  done by a potentially failed upgrade execution one by one in a reverse order.\r
+  I.e. it is like undoing the changes done by the upgrade.\r
+\r
+Restore\r
+  The term refers to a failure handling strategy that reverts the changes\r
+  done by an upgrade by restoring the system from some backup data. This\r
+  results in the loss of any data persisted since the backup has been taken.\r
+\r
+Rollforward\r
+  The term refers to a failure handling strategy applied after a restore\r
+  (from a backup) opertaion to recover any loss of data persisted between\r
+  the time the backup has been taken and the moment it is restored. Rollforward\r
+  requires that data that needs to survive the restore operation is logged at\r
+  a location not impacted by the restore so that it can be re-applied to the\r
+  system after its restoration from the backup.\r
+\r
+Downgrade\r
+  The term refers to an upgrade in which an earlier version of the software\r
+  is restored through the upgrade procedure. A system can be downgraded to any\r
+  earlier version and the compatibility of the versions will determine the\r
+  applicable upgrade strategies and whether service outage can be avoided.\r
+  In particular any data conversion needs special attention.\r

 \r
 \r

-Upgrade Plan (or Campaign?) \r
-   The term refers to a choreography that describes how the upgrade should\r
-   be performed in terms of its targets (i.e. upgrade objects), the\r
-   steps/actions required of upgrading each, and the coordination of these\r
-   steps so that service availability can be maintained. It is an input to an\r
-   upgrade tool (Escalator) to carry out the upgrade \r

 \r
 \r
 Upgrade Objects\r
 \r
 \r
 Upgrade Objects\r


@@ -83,29 +118,33 @@ Upgrade Objects
 Physical Resource\r
 ^^^^^^^^^^^^^^^^^\r
 \r
 Physical Resource\r
 ^^^^^^^^^^^^^^^^^\r
 \r

-Most of cloud infrastructures support dynamic addition/removal of\r
-hardware. A hardware upgrade could be done by adding the new \r
-hardware node and removing the old one. From the persepctive of smooth\r
+Most cloud infrastructures support the dynamic addition/removal of\r
+hardware. Accordingly a hardware upgrade could be done by adding the new\r
+piece of hardware and removing the old one. From the persepctive of smooth\r

 upgrade the orchestration/scheduling of this actions is the primary concern.\r
 upgrade the orchestration/scheduling of this actions is the primary concern.\r

-Upgrading a physical resource,\r
-like upgrading its firmware and/or modify its configuration data, may\r
-also be considered in the future. \r
+Upgrading a physical resource may involve as well the upgrade of its firmware\r
+and/or modifying its configuration data. This may require the restart of the\r
+hardware.\r
+\r

 \r
 \r
 Virtual Resources\r
 ^^^^^^^^^^^^^^^^^\r
 \r
 \r
 \r
 Virtual Resources\r
 ^^^^^^^^^^^^^^^^^\r
 \r

-Virtual resource upgrade mainly done by users. OPNFV may facilitate\r
-the activity, but suggest to have it in long term roadmap instead of\r
-initiate release.\r
+Addition and removal of virtual resources may be initiated by the users or be\r
+a result of an elasticity action. Users may also request the upgrade of their\r
+virtual resources using a new VM image.\r
+\r
+.. Needs to be moved to requirement section: Escalator should facilitate such an\r
+option and allow for a smooth upgrade.\r

 \r
 \r

-.. <MT> same comment here: I don't think the VNF is the virtual\r
-  resource. Virtual resources are the VMs, virtual switches, virtual\r
-  routers, virtual disks etc. The VNF uses them, but I don't think they\r
-  are equal. For example if by some reason the hypervisor is changed and\r
-  the current VMs cannot be migrated to the new hypervisor, they are\r
-  incompatible, then the VMs need to be upgraded too. This is not\r
-  something the NFVI user (i.e. VNFs ) would even know about.\r
+On the other hand changes in the infrastructure, namely, in the hardware and/or\r
+the virtualization facility resources may result in the upgrade of the virtual\r
+resources. For example if by some reason the hypervisor is changed and\r
+the current VMs cannot be migrated to the new hypervisor - they are\r
+incompatible - then the VMs need to be upgraded too. This is not\r
+something the NFVI user (i.e. VNFs ) would know about. In such cases\r
+smooth upgrade is essential.\r

 \r
 \r
 Virtualization Facility Resources\r
 \r
 \r
 Virtualization Facility Resources\r


@@ -189,95 +228,115 @@ result in the same.
 Updating 3 might lead to control plane services interruption if not an\r
 HA deployment.\r
 \r
 Updating 3 might lead to control plane services interruption if not an\r
 HA deployment.\r
 \r

-Upgrade Span\r
-~~~~~~~~~~~~\r

 \r
 \r

-**Major Upgrade**\r

 \r
 \r

-Upgrades between major releases may introducing significant changes in\r
-function, configuration and data, such as the upgrade of OPNFV from\r
-Arno to Brahmaputra.\r

 \r
 \r

-**Minor Upgrade**\r
-\r
-Upgrades inside one major releases which would not leads to changing\r
-the structure of the platform and may not infect the schema of the\r
-system data.\r

 \r
 Upgrade Granularity\r
 ~~~~~~~~~~~~~~~~~~~\r
 \r
 \r
 Upgrade Granularity\r
 ~~~~~~~~~~~~~~~~~~~\r
 \r

-Physical/Hardware Dimension\r
-^^^^^^^^^^^^^^^^^^^^^^^^^^^\r
+The granularity of an upgrade can be characterized from two perspective:\r
+- the physical dimension and\r
+- the software dimension\r
+\r
+\r
+Physical Dimension\r
+^^^^^^^^^^^^^^^^^^\r
+\r
+The physical dimension characterizes the number of similar upgrade objects\r
+targeted by the upgrade, i.e. whether it is full / partial upgrade of a\r
+data centre, cluster, zone.\r
+Because of the upgrade of a data centre or a zone, it may be divided into\r
+several batches. Thus there is a need for efficiency in the execution of\r
+upgrades of potentially huge number of upgrade objects while still maintain\r
+availability to fulfill the requirement of smooth upgrade.\r

 \r
 \r

-Support full / partial upgrade for data centre, cluster, zone. Because\r
-of the upgrade of a data centre or a zone, it may be divided into\r
-several batches. The upgrade of a cloud environment (cluster) may also\r
+The upgrade of a cloud environment (cluster) may also\r

 be partial. For example, in one cloud environment running a number of\r
 be partial. For example, in one cloud environment running a number of\r

-VNFs, we may just try one of them to check the stability and\r
+VNFs, we may just try to upgrade one of them to check the stability and\r

 performance, before we upgrade all of them.\r
 performance, before we upgrade all of them.\r

+Thus there is a need for proper organization of the artifacts associated with\r
+the different upgrade objects. Also the different versions should be able\r
+to coextist beyond the upgrade period.\r
+\r
+From this perspective special attention may be needed when upgrading\r
+objects that are collaborating in a redundancy schema as in this case\r
+different versions not only need to coexist but also collaborate. This\r
+puts requirement on the upgrade objects primarily. If this is not possible\r
+the upgrade campaign should be designed in such a way that the proper\r
+isolation is ensured.\r

 \r
 Software Dimension\r
 ^^^^^^^^^^^^^^^^^^\r
 \r
 \r
 Software Dimension\r
 ^^^^^^^^^^^^^^^^^^\r
 \r

--  The upgrade of host OS or kernel may need a 'hot migration'\r
--  The upgrade of OpenStack’s components\r
+The software dimension of the upgrade characterizes the upgrade object\r
+type targeted and the combination in which they are upgraded together.\r

 \r
 \r

-    i.the one-shot upgrade of all components\r
-       \r
-    ii.the partial upgrade (or bugfix patch) which only affects some\r
-       components (e.g., computing, storage, network, database, message\r
-       queue, etc.)\r
+Even though the upgrade may\r
+initially target only one type of upgrade object, e.g. the hypervisor\r
+the dependency of other upgrade objects on this initial target object may\r
+require their upgrade as well. I.e. the upgrades need to be combined. From this\r
+perspective the main concern is compatibility of the dependent and\r
+sponsor objects. To take into consideration of these dependencies\r
+they need to be described together with the version compatility information.\r
+Breaking dependencies is the major cause of outages during upgrades.\r

 \r
 \r

-.. <MT> this section seems to overlap with 2.1.\r
-  I can see the following dimensions for the software.\r
+In other cases it is more efficient to upgrade a combination of upgrade\r
+objects than to do it one by one. One aspect of the combination is how\r
+the upgrade packages can be combined, whether a new image can be created for\r
+them before hand or the different packages can be installed during the upgrade\r
+independently, but activated together.\r

 \r
 \r

-.. <MT> different software packages\r
+The combination of upgrade objects may span across\r
+layers (e.g. software stack in the host and the VM of the VNF).\r
+Thus, it may require additional coordination between the management layers.\r

 \r
 \r

-.. <MT> different functions - Considering that the target versions of all\r
-   software are compatible the upgrade needs to ensure that any\r
-   dependencies between SW and therefore packages are taken into account\r
-   in the upgrade plan, i.e. no version mismatch occurs during the\r
-   upgrade therefore dependencies are not broken\r
-   \r
-.. <MT> same function - This is an upgrade specific question if different\r
-   versions can coexist in the system when a SW is being upgraded from\r
-   one version to another. This is particularly important for stateful\r
-   functions e.g. storage, networking, control services. The upgrade\r
-   method must consider the compatibility of the redundant entities.\r
+With respect to each upgrade object type and even stacks we can\r
+distingush major and minor upgrades:\r

 \r
 \r

-.. <MT> different versions of the same software package\r
+**Major Upgrade**\r
+\r
+Upgrades between major releases may introducing significant changes in\r
+function, configuration and data, such as the upgrade of OPNFV from\r
+Arno to Brahmaputra.\r
+\r
+**Minor Upgrade**\r
+\r
+Upgrades inside one major releases which would not leads to changing\r
+the structure of the platform and may not infect the schema of the\r
+system data.\r
+\r
+Scope of Impact\r
+~~~~~~~~~~~~~~~\r
+\r
+Considering availability and therefore smooth upgrade, one of the major\r
+concerns is the predictability and control of the outcome of the different\r
+upgrade operations. Ideally an upgrade can be performed without impacting any\r
+entity in the system, which means none of the operations change or potentially\r
+change the behaviour of any entity in the system in an uncotrolled manner.\r
+Accordingly the operations of such an upgrade can be performed any time while\r
+the system is running, while all the entities are online. No entity needs to be\r
+taken offline to avoid such adverse effects. Hence such upgrade operations\r
+are referred as online operations. The effects of the upgrade might be activated\r
+next time it is used, or may require a special activation action such as a\r
+restart. Note that the activation action provides more control and predictability.\r
+\r
+If an entity's behavior in the system may change due to the upgrade it may\r
+be better to take it offline for the time of the relevant upgrade operations.\r
+The main question is however considering the hosting relation of an upgrade\r
+object what hosted entities are impacted. Accordingly we can identify a scope\r
+which is impacted by taking the given upgrade object offline. The entities\r
+that are in the scope of impact may need to be taken offline or moved out of\r
+this scope i.e. migrated.\r
+\r
+If the impacted entity is in a different layer managed by another manager\r
+this may require coordination because taking out of service some\r
+infrastructure resources for the time of their upgrade which support virtual\r
+resources used by VNFs that should not experience outages. The hosted VNFs\r
+may or may not allow for the hot migration of their VMs. In case of migration\r
+the VMs placement policy should be considered.\r

 \r
 \r

-.. <MT> major version changes - they may introduce incompatibilities. Even\r
-   when there are backward compatibility requirements changes may cause\r
-   issues at graceful roll-back\r
-   \r
-.. <MT> minor version changes - they must not introduce incompatibility\r
-   between versions, these should be primarily bug fixes, so live\r
-   patches should be possible\r
-   \r
-.. <MT> different installations of the same software package\r

 \r
 \r

-.. <MT> using different installation options - they may reflect different\r
-   users with different needs so redundancy issues are less likely\r
-   between installations of different options; but they could be the\r
-   reflection of the heterogeneous system in which case they may provide\r
-   redundancy for higher availability, i.e. deeper inspection is needed\r
-   \r
-.. <MT> using the same installation options - they often reflect that the are\r
-   used by redundant entities across space\r
-   \r
-.. <MT> different distribution possibilities in space - same or different\r
-   availability zones, multi-site, geo-redundancy\r
-   \r
-.. <MT> different entities running from the same installation of a software\r
-   package\r
-   \r
-.. <MT>  using different start-up options - they may reflect different users so\r
-   redundancy may not be an issues between them\r
-   \r
-.. <MT> using same start-up options - they often reflect redundant\r
-   entities\r

 \r
 Upgrade duration\r
 ~~~~~~~~~~~~~~~~\r
 \r
 Upgrade duration\r
 ~~~~~~~~~~~~~~~~\r