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,51 @@
 Administrators guide
 ====================
 
-Administrators guide of Fenix.
+Fenix
+=====
+
+Fenix 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. Operations are most optimal when the VNF can be scaled
+according to its current utilization level. This allows for the smallest possible
+maintenance window, with 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 failed. Explained in
+`GET /v1/maintenance/{session_id}/detail`_
+
+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 OpenStack Tacker is looking to support Fenix.
+
+For testing the integration of Fenix, there is `tools`_ directory including
+definitions of sample VNFs, VNFM and admin UI. There are also instructions on
+how to test Fenix example workflows. These tools give an idea of what needs to
+be supported and how to integrate Fenix in the production environment. Note
+that tools only give what needs to be in the VNFM and VNF side for Fenix
+testing purposes. They do not try to have a standard implementation like
+VNFD or other needed interactions on VNF side. What is standard, is the
+interfacing against Fenix.
+
+.. _`GET /v1/maintenance/{session_id}/detail`: ../api-ref/v1/index.html?expanded=get-maintenance-session-details-detail#admin-workflow-session-api
+.. _`tools`: https://opendev.org/x/fenix/src/branch/master/fenix/tools/README.md

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,13 +7,14 @@ 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
 maintenance affecting its instances, it can safely be running somewhere else
-when it happens. The application also get to know about new capabilities coming
+when it happens. The application also gets to know about new capabilities coming
 over infrastructure maintenance/upgrade and can plan its own upgrade at the
 same. As Fenix also provides scaling request towards applications, it is
 possible to make upgrades without adding more resources.
@@ -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
@@ -86,15 +91,15 @@ Project/application having instances on top of the infrastructure under
 maintenance can have a manager (VNFM) to communicate with the maintenance
 session workflow. The manager can subscribe to project specific
 'maintenance.planned' event alarms to get information about maintenance session
-state affecting its instances. The subscription also tells to the workflow that
+state affecting its instances. The subscription also tells the workflow that
-the project have a manager capable of communicating with the workflow.
+the project has a manager capable of communicating with the workflow.
 Otherwise, workflow should have a default behavior towards project instances,
 or fail if communication is mandatory in your cloud use case. There is also
 a project-specific API to query its instances under current maintenance
 workflow session state and to answer back to workflow.
 
 Any infrastructure service can also be made to support 'maintenance.host'
-notification. This notification is telling wether a host is in maintenance or
+notification. This notification is telling whether a host is in maintenance or
 back in normal use. This might be important for enabling/disabling self-healing
 or billing. Notification can also be used to indicate when a host is added or
 removed.
@@ -102,7 +107,7 @@ removed.
 High level sequence diagram
 ===========================
 
-This is the original design idagram not utilizing the ETSI defined
+This is the original design diagram not utilizing the ETSI defined
 instance and instance group constraints.
 
 .. seqdiag::
@@ -131,7 +136,7 @@ instance and instance group constraints.
     }
 
 
-This advanced idagram utilizing the ETSI defined instance and instance group
+This advanced diagram utilizing the ETSI defined instance and instance group
 constraints.