x/fenix
Code Issues Proposed changes

Administrator quide and other documentation

Browse Source 
Some details of how to take Fenix into use.

Change-Id: I820aae66ba4bd0ce500c2d6797d852bbf39ef895
Signed-off-by: Tomi Juvonen <tomi.juvonen@nokia.com>
This commit is contained in:
Tomi Juvonen 2020-04-20 10:08:13 +03:00
parent 244fb3ced0
commit bd0810495f
4 changed files with 94 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
README.rst
View File

@ -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
implement own simple manager for any application.
with the application on top of it. In Telco world we talk about VNFM, but one can
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
time for its service. Interaction gives ability for application manager 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
to re-instantiate his instance or have Fenix to make migration. Also scaling
application or retirement will be possible.
infrastructure in interaction with the application manager to guarantee zero
downtime for its service. Interaction gives the ability for the application manager
to know about new capabilities coming over maintenance to make his own upgrade.
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 the migration. Also scaling
applications or retirement will be possible.
As Fenix will have project specific messaging with information about instances
affected towards application manager, it will also have admin level messaging.
This messaging can tell what host is down for maintenance, so any
infrastructure components can have this information. Special case for this
would also be telling about adding or removing a host.
As Fenix has project-specific messaging with information about instances
affected towards the application manager, it will also have admin-level messaging.
This messaging can tell what host is down for maintenance, back in use, added
or retired. Any infrastructure component can catch this information as needed.
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

49
doc/source/admin/index.rst
View File

@ -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

8
doc/source/cli/index.rst
View File

@ -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.

23
doc/source/user/architecture.rst
View File

@ -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,
but the aim is to have a wider scope, like edge (Akraino) and Airship.
virtual machines and containers. Current workflows are for OpenStack and
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
the project have a manager capable of communicating with the workflow.
state affecting its instances. The subscription also tells the workflow that
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.