diff --git a/doc/source/configuration/configuration.rst b/doc/source/configuration/configuration.rst new file mode 100644 index 0000000..e0bda77 --- /dev/null +++ b/doc/source/configuration/configuration.rst @@ -0,0 +1,69 @@ +Configuration files +------------------- + +Configuration options. All options have default values. Mandatory options are +mentioned as those are usually at least the ones needed to be defined to match +to the current system. + + * Edit the ``/etc/fenix/fenix-api.conf`` file the configure fenix-api + + .. code-block:: ini + + [DEFAULT] + + #Mandatory configuration options + + #Host where API is running. default="127.0.0.1" + host = + #API Port. default=5000 + port = + #An URL representing the messaging driver to use and its full configuration. + transport_url = + + * Edit the ``/etc/fenix/fenix.conf`` file the configure fenix-engine + + .. code-block:: ini + + [DEFAULT] + + #Mandatory configuration options + + #Host where engine is running. default="127.0.0.1" + host = + #API Port. default=5000 + port = + #An URL representing the messaging driver to use and its full configuration. + transport_url = + + #Optional configuration options + + #Wait for project reply after message sent to project. default 120 + wait_project_reply = 120 + #Project maintenance reply confirmation time in seconds. default 40 + project_maintenance_reply = 40 + #Project scale in reply confirmation time in seconds. default 60 + project_scale_in_reply = 60 + #Number of live migration retries. default 5 + live_migration_retries = 5 + #How long to wait live migration to be done. default 600 + live_migration_wait_time = 600 + + [database] + + #database connection URL + connection = mysql+pymysql://fenix:FENIX_DBPASS@controller/fenix + + [service_user] + + #OpenStack Identity service URL. Default to environmental variable OS_AUTH_URL + os_auth_url = http://127.0.0.1/identity + #Fenix user. Must have admin role. Default to environmental variable OS_USERNAME + os_username = admin + #Fenix admin user password. Default to environmental variable OS_PASSWORD + os_password = admin + #A domain name the os_username belongs to. Default to environmental variable OS_USER_DOMAIN_NAME + os_user_domain_name = default + #The Fenix admin project. Default to environmental variable OS_PROJECT_NAME + os_project_name = admin + #The Fenix admin project domain. Default to environmental variable OS_PROJECT_DOMAIN_NAME + os_project_domain_name = default diff --git a/doc/source/configuration/dependencies.rst b/doc/source/configuration/dependencies.rst new file mode 100644 index 0000000..e69f36a --- /dev/null +++ b/doc/source/configuration/dependencies.rst @@ -0,0 +1,80 @@ +.. _dependencies: + +Fenix external dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nova +---- + +Fenix will normally use cold and live migrations. For these to work, Nova +service user should be configured to be able to ssh between compute nodes. +You may also want to change some other related configuration parameters. + +AODH and Ceilometer configuration +--------------------------------- + +When want to utilize the VNF(M)/EM interaction with Fenix, VNF needs to +supbscribe to AODH event alarm for 'maintenance.scheduled' type of +notifications. + +Any service may also want to know when host is added, retired, in maintenance +or back from maintenance. For this those services can subscribe to AODH event +alarm for 'maintenance.host' type of notification. + + * /etc/ceilometer/event_definitions.yaml + + .. code-block:: yaml + + - event_type: maintenance.scheduled + traits: + actions_at: + fields: payload.maintenance_at + type: datetime + allowed_actions: + fields: payload.allowed_actions + host_id: + fields: payload.host_id + instances: + fields: payload.instances + metadata: + fields: payload.metadata + project_id: + fields: payload.project_id + reply_url: + fields: payload.reply_url + session_id: + fields: payload.session_id + state: + fields: payload.state + - event_type: maintenance.host + traits: + host: + fields: payload.host + project_id: + fields: payload.project_id + session_id: + fields: payload.session_id + state: + fields: payload.state + + * /etc/ceilometer/event_pipeline.yaml + + .. code-block:: yaml + + - notifier:// + - notifier://?topic=alarm.all + +For AODH and Ceilometer configuration to take into effect, you may want to +restart corresponding services + + .. code-block:: console + + $ sudo systemctl restart openstack-aodh-listener.service + $ sudo systemctl restart openstack-ceilometer-notification.service + +In DevStack you may want to enable Ceilometer and AODH in local.conf + + .. code-block:: ini + + enable_plugin ceilometer https://opendev.org/openstack/ceilometer + enable_plugin aodh https://opendev.org/openstack/aodh diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index df5d9c7..896397c 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -2,4 +2,18 @@ Configuration ============= -Configuration of fenix. +.. toctree:: + :maxdepth: 2 + + configuration.rst + +Dependencies and special configuration +====================================== + +Fenix Default workflow VNFM interaction also assumes AODH is installed. +Among that, here is mentioned what you may want to configure when using Fenix. + +.. toctree:: + :maxdepth: 2 + + ../configuration/dependencies.rst diff --git a/doc/source/install/common_configure.rst b/doc/source/install/common_configure.rst deleted file mode 100644 index 23b8fdb..0000000 --- a/doc/source/install/common_configure.rst +++ /dev/null @@ -1,10 +0,0 @@ -2. Edit the ``/etc/fenix/fenix.conf`` file and complete the following - actions: - - * In the ``[database]`` section, configure database access: - - .. code-block:: ini - - [database] - ... - connection = mysql+pymysql://fenix:FENIX_DBPASS@controller/fenix diff --git a/doc/source/install/common_prerequisites.rst b/doc/source/install/common_prerequisites.rst index c014506..70690e5 100644 --- a/doc/source/install/common_prerequisites.rst +++ b/doc/source/install/common_prerequisites.rst @@ -63,6 +63,11 @@ you must create a database, service credentials, and API endpoints. $ openstack service create --name fenix --description "fenix" fenix + Note! In Fenix workflow you may want to have ssh access to all nodes for + your Fenix action plug-ins to scp filex and locally execute scripts on + those nodes. This means you may want to have the ssh without password + configured for Fenix service user. + #. Create the fenix service API endpoints: .. code-block:: console @@ -73,3 +78,15 @@ you must create a database, service credentials, and API endpoints. fenix internal http://controller:XXXX/vY/%\(tenant_id\)s $ openstack endpoint create --region RegionOne \ fenix admin http://controller:XXXX/vY/%\(tenant_id\)s + +Installation +------------ + +Note! Fenix is not currently included to Linux distros. +You need to clone and install from source. + + .. code-block:: console + + $ git clone https://opendev.org/x/fenix + $ cd fenix + $ sudo python setup.py install diff --git a/doc/source/install/get_started.rst b/doc/source/install/get_started.rst index 00c318b..2d543c0 100644 --- a/doc/source/install/get_started.rst +++ b/doc/source/install/get_started.rst @@ -6,4 +6,7 @@ The fenix service provides... The fenix service consists of the following components: ``fenix-api`` service - Accepts and responds to end user compute API calls... + Accepts and responds to end user API calls + +``fenix-engine`` service + Runs the pluggable maintenance sessions diff --git a/doc/source/install/install-devstack.rst b/doc/source/install/install-devstack.rst new file mode 100644 index 0000000..2d2d9e1 --- /dev/null +++ b/doc/source/install/install-devstack.rst @@ -0,0 +1,18 @@ +.. _install-devstack: + +Install and configure for DevStack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install and configure components +-------------------------------- + +#. Install Fenix by adding needed options to local.conf + + .. code-block:: ini + + #Enable Fenix plugin + enable_plugin fenix https://opendev.org/x/fenix + + #Enable Fenix services + enable_service fenix-engine + enable_service fenix-api diff --git a/doc/source/install/install-obs.rst b/doc/source/install/install-obs.rst index ba6d09e..2bdffa5 100644 --- a/doc/source/install/install-obs.rst +++ b/doc/source/install/install-obs.rst @@ -5,21 +5,11 @@ Install and configure for openSUSE and SUSE Linux Enterprise ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes how to install and configure the fenix service -for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1. +for openSUSE and SUSE Linux Enterprise Server. .. include:: common_prerequisites.rst -Install and configure components --------------------------------- - -#. Install the packages: - - .. code-block:: console - - # zypper --quiet --non-interactive install - -.. include:: common_configure.rst - +.. include:: ../configuration/configuration.rst Finalize installation --------------------- @@ -29,6 +19,8 @@ the system boots: .. code-block:: console - # systemctl enable openstack-fenix-api.service + # sudo systemctl enable openstack-fenix-api.service + # sudo systemctl start openstack-fenix-api.service - # systemctl start openstack-fenix-api.service + # sudo systemctl enable openstack-fenix-engine.service + # sudo systemctl start openstack-fenix-engine.service diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst index 310db5f..75bfd11 100644 --- a/doc/source/install/install-rdo.rst +++ b/doc/source/install/install-rdo.rst @@ -5,20 +5,11 @@ Install and configure for Red Hat Enterprise Linux and CentOS This section describes how to install and configure the fenix service -for Red Hat Enterprise Linux 7 and CentOS 7. +for Red Hat Enterprise Linux and CentOS. .. include:: common_prerequisites.rst -Install and configure components --------------------------------- - -#. Install the packages: - - .. code-block:: console - - # yum install - -.. include:: common_configure.rst +.. include:: ../configuration/configuration.rst Finalize installation --------------------- @@ -28,6 +19,8 @@ the system boots: .. code-block:: console - # systemctl enable openstack-fenix-api.service + # sudo systemctl enable openstack-fenix-api.service + # sudo systemctl start openstack-fenix-api.service - # systemctl start openstack-fenix-api.service + # sudo systemctl enable openstack-fenix-engine.service + # sudo systemctl start openstack-fenix-engine.service diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst index afefe63..510b8f8 100644 --- a/doc/source/install/install-ubuntu.rst +++ b/doc/source/install/install-ubuntu.rst @@ -4,22 +4,11 @@ Install and configure for Ubuntu ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes how to install and configure the fenix -service for Ubuntu 14.04 (LTS). +service for Ubuntu. .. include:: common_prerequisites.rst -Install and configure components --------------------------------- - -#. Install the packages: - - .. code-block:: console - - # apt-get update - - # apt-get install - -.. include:: common_configure.rst +.. include:: ../configuration/configuration.rst Finalize installation --------------------- @@ -28,4 +17,5 @@ Restart the fenix services: .. code-block:: console - # service openstack-fenix-api restart + # sudo service openstack-fenix-api restart + # sudo service openstack-fenix-fenix restart diff --git a/doc/source/install/install.rst b/doc/source/install/install.rst index 830d989..39f394e 100644 --- a/doc/source/install/install.rst +++ b/doc/source/install/install.rst @@ -7,14 +7,17 @@ This section describes how to install and configure the fenix service, code-named fenix, on the controller node. This section assumes that you already have a working OpenStack -environment with at least the following components installed: -.. (add the appropriate services here and further notes) +environment. Note that installation and configuration vary by distribution. +Currently Fenix is not included in any distributions. Instead +there is shown the generic way of installing and how to install +via DevStack. .. toctree:: :maxdepth: 2 - install-obs.rst install-rdo.rst install-ubuntu.rst + install-obs.rst + install-devstack.rst diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst index b3f58b5..fe77030 100644 --- a/doc/source/install/next-steps.rst +++ b/doc/source/install/next-steps.rst @@ -3,7 +3,5 @@ Next steps ~~~~~~~~~~ -Your OpenStack environment now includes the fenix service. - -To add additional services, see -https://docs.openstack.org/project-install-guide/ocata/. +Latest activites are tracked in wiki page: +https://wiki.openstack.org/wiki/Fenix diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst index 9973d8b..0570b3c 100644 --- a/doc/source/install/verify.rst +++ b/doc/source/install/verify.rst @@ -9,16 +9,9 @@ Verify operation of the fenix service. Perform these commands on the controller node. -#. Source the ``admin`` project credentials to gain access to - admin-only CLI commands: - - .. code-block:: console - - $ . admin-openrc - #. List service components to verify successful launch and registration - of each process: + of each process. Example for DevStack: .. code-block:: console - $ openstack fenix service list + $ sudo systemctl status devstack@fenix* diff --git a/doc/source/library/index.rst b/doc/source/library/index.rst index 746eafe..2688f9c 100644 --- a/doc/source/library/index.rst +++ b/doc/source/library/index.rst @@ -4,4 +4,4 @@ Usage To use fenix in a project:: - import fenix + TBD