Administrator quide and other documentation

Some details of how to take Fenix into use.

Change-Id: I820aae66ba4bd0ce500c2d6797d852bbf39ef895
Signed-off-by: Tomi Juvonen <tomi.juvonen@nokia.com>

README.rst

@@ -2,26 +2,36 @@
 Fenix
 =====
 
-OpenStack host maintenance and upgrade in interaction with application
+OpenStack host maintenance and upgrade in interaction with the application
 
 Fenix implements rolling infrastructure maintenance and upgrade in interaction
-with application on top of it. In Telco world we talk about VNFM, but one can
+with the application on top of it. In Telco world we talk about VNFM, but one can
-implement own simple manager for any application.
+implement his own simple manager for any application.
 
 Infrastructure admin can call Fenix API to start a maintenance workflow
 session. This session will make needed maintenance and upgrade operations to
-infrastructure in interaction with application manager to guarantee zero down
+infrastructure in interaction with the application manager to guarantee zero
-time for its service. Interaction gives ability for application manager to
+downtime for its service. Interaction gives the ability for the application manager
-know about new capabilities coming over maintenance to make his own upgrade.
+to know about new capabilities coming over maintenance to make his own upgrade.
-Application can have a time window to finish what he is doing, make own action
+The application can have a time window to finish what he is doing, make own action
-to re-instantiate his instance or have Fenix to make migration. Also scaling
+to re-instantiate his instance or have Fenix to make the migration. Also scaling
-application or retirement will be possible.
+applications or retirement will be possible.
 
-As Fenix will have project specific messaging with information about instances
+As Fenix has project-specific messaging with information about instances
-affected towards application manager, it will also have admin level messaging.
+affected towards the application manager, it will also have admin-level messaging.
-This messaging can tell what host is down for maintenance, so any
+This messaging can tell what host is down for maintenance, back in use, added
-infrastructure components can have this information. Special case for this
+or retired. Any infrastructure component can catch this information as needed.
-would also be telling about adding or removing a host.
+
+Fenix also works with "one-click". Infrastructure admin just creates the
+workflow session he wants and all needed software changes are automatically
+downloaded, the workflow is run to wanted hosts according to the request and
+depending on how the used workflow plug-in and action plug-ins are
+implemented.
+
+In the NFV Fenix needs to be supported by infrastructure admin UI, VNFM and
+VNF implementation. Fenix itself should be integrated into infrastructure
+to be used it the infrastructure maintenance, upgrade, scaling and life-cycle
+operations.
 
 * Free software: Apache license
 * Documentation: https://fenix.readthedocs.io/en/latest/index.html

doc/source/admin/index.rst

@@ -2,4 +2,43 @@
 Administrators guide
 ====================
 
-Administrators guide of Fenix.
+Fenix
+=====
+
+Fenix itself should be deployed to the infrastructure controller- or
+manager-node and be used for any cloud infrastructure maintenance, upgrade,
+scaling or life-cycle operations.
+
+VNF and VNFM
+============
+
+In the NFV use case, the VNF and VNFM need to support Fenix to optimize the
+workflows and to guarantee zero impact to VNF during different infrastructure
+operations. This means instance and instance group constraints and the
+interaction with Fenix. Best optimization will be if the VNF can be scaled
+according to its current utilization level. This will result in the smallest
+possible maintenance window while keeping the zero impact on the VNF service.
+
+Infrastructure Admin UI
+=======================
+
+Infrastructure admin UI needs to support Fenix. UI needs to be able to call
+the Fenix admin APIs and preferably listen to Fenix admin events. UI should
+be able to call different infrastructure maintenance and upgrade workflows
+with needed parameters. APIs and events also give the possibility to have
+detailed information about the workflow progress and to troubleshoot possible
+errors. In complex clouds, errors can be still simple and quickly corrected
+even manually. In this kind of special case, the UI can also support updating
+Fenix workflow session to continue exactly where it left.
+
+Integration
+===========
+
+The above-mentioned UI, VNF and VNFM are currently not in the scope of Fenix.
+The implementation should be in other open-source projects or own proprietary
+solutions. Currently, at least the OpenStack Tacker is looking to support Fenix.
+
+the Fenix itself also need to be tested and for that, there is some kind of command-line
+implementation for the above functionality made under Fenix 'tools'. The Implementation
+aims to have the ability to test the Fenix sample workflows with sample a application
+(VNF). It also gives an idea what needs to be supported.

doc/source/cli/index.rst

@@ -3,3 +3,11 @@ Command line interface reference
 ================================
 
 CLI reference of Fenix.
+
+Currently, Fenix does not implement CLI. Real product integration is
+expected to have GUI and VNFM (application manager) to support Fenix.
+In the OPNFV Doctor, the maintenance test case implements infrastructure
+admin and VNFM behavior. In Fenix, you can find 'infra_admin.py' and
+'vnfm.py' that implements the same and are always up-to-date to be tested
+against Fenix example workflows. Those are anyhow just for the testing sample
+application but works to get the idea for product implementation.

doc/source/user/architecture.rst

@@ -7,8 +7,9 @@ Fenix Architecture
 Fenix is an engine designed to make a rolling infrastructure maintenance and
 upgrade possible with zero downtime for the application running on top of it.
 Interfaces are designed to be generic, so they can work with different clouds,
-virtual machines and containers. The first use case is with OpenStack and VMs,
+virtual machines and containers. Current workflows are for OpenStack and
-but the aim is to have a wider scope, like edge (Akraino) and Airship.
+Kubernetes, but the workflow plug-in implementation defines what kind
+of cloud you want to support.
 
 The key in Fenix providing the zero downtime is to have an ability to
 communicate with an application manager (VNFM). As the application is aware of
@@ -55,10 +56,14 @@ plug-ins can be implemented for different clouds and deployments.
 
 **action plug-ins** are called by the workflow plug-in. It is possible to have
 different type of plug-ins, and if there is more than one of a specific type,
-one can also define the order they are executed:
+one can also define the order they are executed. These types are currently in
+use in the Fenix example workflows. You can always define your own type
+according to your workflow implementation:
 
 * **pre** plug-in is run first
 * **host** plug-in is run for each host
+* **compute** plug-in is run on each compute host
+* **controller** plug-in is run on each controller host
 * **post** plug-in is run last
 
 There is a possibility to define 'metadata' to further indicate plug-in