Skip to content

Latest commit

 

History

History
159 lines (112 loc) · 13.7 KB

README.md

File metadata and controls

159 lines (112 loc) · 13.7 KB
Raw

UFM Plugins

Overview

UFM plugins are service programs that can be dynamically loaded to extend the functionality of UFM Enterprise.

The plugins are Docker containers, and their life cycle is being managed by UFM.

Functions commonly added by optional UFM plugins include:

  • REST-over-RDMA (REST requests over IB to the UFM server)
  • NDT (NDT topo diff)
  • TFS (Telemetry Fluentd Streaming)
  • EFS (UFM Event Fluentd Streaming)
  • AHX Monitoring (Monitoring HDR director switch cooling devices)

Architecture

  • Security, AAA
  • lifecycle management for
    • Deployment
    • Configuration
    • Health monitoring
    • State persistency
    • HA
  • Presentation (UI)
  • Allows UFM capabilities extension by 3rd parties

Build

  • The plugin’s Docker container image name convention is ufm-plugin- (e.g., mellanox/ufm-plugin-tfs) with any tag (default tag is “latest”).

  • Each plugin should consist of the following files:

    1. init.sh : Initialize script that should be placed in the root folder (/init.sh) and have execute permission. It is being invoked by the UFM plugin manager upon plugin deployment (when adding a new plugin). The developer may copy the plugins configuration files to /config folder which is mapped to the DRBD partition on the host (location on host: /opt/ufm/files/conf/plugins/{plugin name})

    2. deinit.sh : De-initialize script that should be placed in the root folder (/deinit.sh), have execute permission and return zero. It is being invoked by the UFM plugin manager upon plugin removal. The developer may clear files and folders that are placed on the host (e.g., log files)

    3. upgrade.sh : This is the upgrade script, which should be placed in the root folder (/upgrade.sh) and granted execute permission. It is invoked by the UFM plugin manager upon plugin upgrade. During the upgrade stage, the developer may handle the upgrade of the plugin's configuration files. If the upgrade is successful (i.e., exits with zero), the new plugin's TAG (version) will be updated in the plugins' configuration file located at /opt/ufm/files/conf/ufm_plugins.conf.

  • Each plugin may have the following files:

    1. {plugin name}_shared_volumes.conf : Contains a list of folders that are mapped between the host and the container. It consists of multiple lines in format “:” (e.g., /opt/ufm/files/conf:/opt/ufm/files/conf).

      • The following folders are shared between the host and the container by default:

        1. {UFM files path}/conf/plugins/{plugin name}:/config : This folder should contain the plugin’s configuration files. It is managed by DRBD (in case of HA) and thus, it is replicated between master and standby nodes.
        2. {UFM files path}/log/plugins/{plugin name}:/log : This folder should contain the plugin’s log files. It is managed by DRBD (in case of HA) and thus, it is replicated between master and standby nodes.
        3. /opt/ufm/ufm_plugins_data/{plugin name}:/data : This folder may contain the plugin’s data files that should be persistent. Please note that this folder is not managed by DRBD (in case of HA) and thus, it will not be replicated between the master and standby nodes on the failover.

      • Note: The default folders are being removed by the UFM plugin manager upon plugin’s removal, while the plugin is responsible to remove all the files and folders which are mapped to host and are listed in shared volumes configuration file (e.g., logs files that were written to /log folder in the container which is mapped to /opt/ufm/files/log folder on the host)

    2. {plugin name}_httpd_proxy.conf : Contains the port that UFM may use to forward the plugin’s HTTP request. It consists of one line in format “port={port number}”. All the HTTP requests to the plugin are being forwarded by the UFM server (authentication is handled by UFM).

    3. ufm_plugin_{plugin name}_httpd.conf : This file contains the Apache configuration for the plugin, redirecting HTTP requests from Apache directly to the plugin's web server. These requests are not authenticated by UFM.

    4. {plugin name}_runtime_args.conf : This file serves as the configuration file for the runtime plugin's resources. It consists of key-value arguments (e.g., cpus=1.5). Currently, only CPU limits are supported.

  • Note: The configuration files _{plugin name}shared_volumes.conf , _{plugin name}httpd_proxy.conf and any custom configurations files must be copied to /config folder upon plugin deployment for UFM to manage the plugin (the plugins configuration is written to {UFM files path}/conf/ufm_plugins.conf

  • The plugins’ ports range is 8900 - 8999. The following ports are in use:

    • GRPC: 8901
    • AHX: 8910
    • NDT: 8980
    • EFS: 8989
    • TFS: 8981
    • Grafana: 8982,8983,8984

  • UFM Health monitors the plugin to make sure it is up and running. The following test definition should be added to each plugin in UFMHealthConfiguration.xml:

    <Test Name="<test_name>" NumOfRetriesBeforeGiveup="3" RetryTimeoutInSeconds="30">
        <TestOperation Name="PluginIsRunningTest">
            <Parameters> 
                <Parameter Name="PluginName" Value="<plugin_name>"/> 
                <Parameter Name="RunInMonitoringMode" Value="No"/> 
                <Parameter Name="RunInManagementMode" Value="Yes"/> 
            </Parameters> 
        </TestOperation>
        <CorrectiveOperation Name="RestartPlugin">
            <Parameters>
                <Parameter Name="PluginName" Value="<plugin_name>"/> 
            </Parameters> 
        </CorrectiveOperation>
        <GiveupOperation Name="None"/>
    </Test>
    ....
    <Test Name="<test_name>">
        <Frequency Value="1" MeasurementUnit="Minutes"/>
    </Test>

Lifecycle

The UFM plugins lifecycle is managed by UFM. Currently, It is the user responsibility to pull/load the plugin’s Docker container image on both master and standby nodes.

  • Add : Upon addition, the plugin’s Docker container is started, and the /init.sh script is invoked. Its configuration files must be copied to /config folder. The container will exit once the init stage is done and it will be re-started upon UFM startup. In case UFM is already running when the plugin is deployed, it will be started automatically.

  • Disable : The plugin’s Docker container is stopped. However, its data is still accessible via the host.

  • Enable : The plugin’s Docker container is re-started.

  • Remove : The plugin’s Docker container is stopped, and the /deinit.sh script is being invoked. In this stage, all the plugin’s data is removed.

  • Upgrade : The plugin's /upgrade.sh script is invoked once the plugin is stopped, either manually before the upgrade or via the optional "force" flag. In this stage, all the plugin's data may be upgraded. It is up to the developer to decide whether the data needs to be upgraded. The upgrade.sh script receives the plugin's new TAG (version) as an argument ("-to_version {TAG}"). If the upgrade is successful (i.e., exits with zero), the new plugin's TAG (version) will be updated in the plugins' configuration file located at /opt/ufm/files/conf/ufm_plugins.conf. The developer should decide how to proceed in case the upgrade has failed (e.g., revert to the old configuration and return a non-zero value, or reset to the new configuration with default values and return zero).

Note: The plugin’s Docker container is started/stopped upon UFM start/stop. In case UFM is already running when the plugin is added/enabled, it will be started. While, in case it is disabled/removed, it will be stopped

Authentication

UFM PLUGINS AUTHENTICATION

Plugin and Configurations REST APIs

The plugin's configurations should be controllable via the REST APIs (either to get the current configuration or to update/change specific configurations), and to do so we are providing basic python flask server to serve the configurations or any extra plugin's REST API by extending it in your plugin's code.

Extendable UI Plugins

The plugin may contain separated UI (Angular) application that contains new panels/views/functionalities. and These views could be deployed as part of the UFM Web GUI or as standalone applications.

In case of deploying the UI as part of UFM Web GUI, you need to define {plugin name}_ui_conf.json, which defines the views/components that are being to be added to the UFM and where they should be added (under which section or menu or tab). Please make sure to copy this file to /config at the plugin's deployment stage.

Currently, the UFM supports extending the following areas:

  1. Adding new items to the main UFM left navigation menu [a.k.a 'leftMenu' or 'dynamicLeftMenuItems'].
  2. Adding new items to the context menu of the selected devices [a.k.a 'deviceContextMenu'].
  3. Adding new tabs under the Settings view [a.k.a 'settingsDetailsTabs'].
  4. Adding new tabs under the selected device's information view [a.k.a 'deviceDetailsTabs'].
  5. Hooking the devices data table [a.k.a 'devicesDataTable'].
  6. Replacing any existing view under the UFM GUI with new plugin's view [a.k.a 'existingRoute'].

UI Configuration Parameters Details:

Parameter Required Description
mfEntry True URL for the remoteEntry.js path that will be generated after compiling the UI application
name True Name of the plugin's UI application
exposedModule True Name of the exposed module in the webpack configurations
ngModuleName True Class Name of the exposed module in typescript
hookInfo.type True The Type of the added module/view, it should be one of the following types:['leftMenu', 'dynamicLeftMenuItems', 'devicesDataTable', 'deviceDetailsTabs' ,'settingsDetailsTabs' ,'deviceContextMenu', 'existingRoute']
hookInfo.route True The name of the new/existing UFM route that the added module/view should be added to (in case of type 'existingRoute', this attribute could be a string or a regex)
hookInfo.label True The displayed name of the added menu/tab
hookInfo.key True The unique key of the added menu/tab
hookInfo.pluginRoute False The plugin's route that the UFM should navigate to it after loading the plugin's module/view
hookInfo.order False The order of the added menu's item / tab
hookInfo.icon False Fontawsome class to menu icons

You can find this sample json that contains all the supported flows

Hello-world plugin examples

We are providing basic-hello-world plugin example that contains a simple python flask server with simple API

  • To build the example plugin image, you can execute the build/docker_build.sh script.
  • The output of the build script is the plugin's image.
  • You need to load the image:

docker load -i build/ufm-plugin-basic_hello_world_latest-docker.img.gz

  • Once the image is loaded, it will be discovered by the UFM Plugins Manager and manage it either by UFM Web GUI -> Settings -> Plugins Management or by the Plugins UFM REST API
  • Once the plugin is added & started, the plugin's REST API will be accessible and also the configured UI views will be added to the UFM GUI.

And also we are providing an advanced hello-world plugin example that contains an advanced python server with some Angular UI components.