Morpheus Plugin Documentation

Note: Morpheus Plugin API is now 1.0! This means calls that are used will be supported for a longer period of time and given appropriate deprecation warnings when necessary. Morpheus Plugin API 1.0 requires a minimum Morpheus Version of 6.3.0. Morpheus 6.2.x still runs on Core version 0.15.x

Create a new project with a build.gradle file. We will use the shadowjar plugin to create our "fat jar"

To let the Morpheus plugin manager know what class to load you must specify the class in jar’s manifest:

When writing plugin code, it is important to note a typical groovy/java project folder structure

Be sure to configure your .gitignore file to ignore the build/ directory which appears after performing your first build.

Most of the folder structure can be self-explanatory if familiar with groovy/java. Project packages live within src/main/groovy and contain source files ending in .groovy. View resources are stored in the src/main/resources subfolder and vary depending on the view renderer of choice. While static assets like icons or custom javascript live within the src/assets folder. This is handled by the Asset Pipeline plugin. View rendering and static assets will be covered in more detail later.

Building a project is as simple as calling

NOTE: If the gradle wrapper does not yet exist, simply run gradle wrapper within the root of the project to generate the wrapper.

The resulting jar will exist, by default, in the build/libs directory of the project.

Following the example above, create your plugin class under src/main/java/com/example/MyPlugin.java

Your plugin must extend the com.morpheus.core.Plugin class:

Here we see a basic plugin that initializes some metadata (the Plugin Name) and registers a custom tab provider.

A plugin may contain any number of Plugin Providers. A Plugin Provider contains the functionality of your plugin such as a Custom Tab, IPAM, Backup Provider, etc.

There are provided classes such as TaskProvider, ProvisionProvider, ApprovalProvider, ReportProvider, InstanceTabProvider, ServerTabProvider, and others to get you started building your provider. For example the InstanceTabProvider provides a renderer, show method, and security checking method to make it easy to build your own custom tab on the instance page.

Providers are registered in your plugin during the initialize() method call within the Plugin class as can be seen in the MyPlugin.java sample seen above.

As of 0.8.0 Plugins can now have settings that can be applied globally after installing a plugin. Some users may use this to configure an integration to a third party service like Datadog, or affect how providers may behave based on some setting. These can be set after uploading a plugin in Administration → Integrations → Plugins.

Settings, much like any other form aspect of a plugin, can take advantage of OptionType and OptionProvider entities to configure how the options are presented to the user and what options are available to choose from.

Implementing the above getter method allows one to specify the form option-types of settings that could be saved by the user.

Fetching setting values for use in a provider can easily be accomplished via the morpheusContext. There is a method that returns a JSON String of the setting values that is up to the plugin developer to deserialize called morpheusContext.getSettings(Plugin plugin). Simply pass the plugin class instance to it and an rxJava Single<String> is returned.

In an effort to make plugin development easier, it was decided that a counterpart service would be made for non rxjava / reactive calls. We call this the SynchronousDataService. This service provides the exact same methods as the MorpheusDataService, however, it does not require an Observable subscription or blockingGet().

These services can be accessed via the contexts morpheusContext.getServices() directive as opposed to morpheusContext.getAsync(). They are useful for things that you know are going to block anyway, such as perhaps a UI Page render.

It is still recommended, when performing sync operations of a cloud, or generating a custom report to utilize the asynchronous counterparts for best performance.

NOTE: As of 0.15.3: Not All Async services have been converted yet and several may still be missing.

Incoming requests come with a ViewModel object populated with the http request & response details.

Route provides a builder to allow your plugin to easily build a route with permissions. It takes the url, the method in this class to call, and a list of permissions which can be built with the Permission builder.

The route can either return:

After creating a PluginController, register it in your plugin like so:

Below is an example API Call taken from the Infoblox plugin.

There are several methods to call the api and automatically handle certain payload formats such as callJsonApi, callXmlApi, or plain callApi.

Options can be passed relating to the request via the HttpApiClient.RequestOptions object. Please refer to the java api doc for available options.

Views are stored in your plugin at src/main/resources/renderer/<plugin scope>/<your view>.hbs. Many plugin providers provide a convention to store views that will be rendered.

If you wish to render and return html manually you can call the renderer directly:

Do not provide the suffix (.hbs) - you may also pass a com.morpheusdata.views.ViewModel into the view to use when rendering the html.

The template engine can also process static assets such as images, css, and javascript for you. Place your assets under src/assets/{plugin-code}. To include them in the plugin template you can use the {{ asset }} handlebars helper as so:

Plugin localization files are global. This means, if a language pack did not exist for the entire Morpheus Appliance for a specific locale and a developer/partner wanted to make one as a plugin, they could. The plugins properties are automatically checked system-wide. It is even possible to override single labels in the morpheus appliance if so desired.

For information on localizing Morpheus, please refer to the Morpheus Crowdin Localization Plugin

To get started, simply create an implementation of a DataSetProvider or with some convenience methods AbstractDataSetProvider.

Now, when defining your OptionType simply set your optionSource property to the getKey() defined in your provider. It is important not to conflict names with other plugins so please try to use a unique method name. Additionally, datasets can be isolated using the getNamespace() method. This should be set in the optionoSourceType of your OptionSource definition.

To get started, simply create an implementation of an OptionSourceProvider. The primary implementation method is called getMethodNames and just returns a list of methods on the class that are accessed via API as datasets.

Above is an example option source registered for the Google Cloud Plugin. NOTE: Every method must have a singular input argument of type Object (which is the default in Groovy). In reality, it is a Map containing passed in params from the api call that can be referenced as well as the current user object. It is also worth noting that the return type expected is a List<Map<String,String>> whereby the properties on the map are of keys name,value.

Now, when defining your OptionType simply set your optionSource property to the field name defined in your provider. It is important not to conflict names with other plugins so please try to use a unique method name.

Most of the time, this setup will be used when defining available OptionTypes in the various Provider types that have them. For example, an IPAMProvider as a method for getIntegrationOptionTypes(). The idea is to also support local credential inputs like the simple serviceUsername and servicePassword fields. To do this simply add the flag localCredential:true to those fields so the system knows, when using local credentials, to show those fields. An example of a credential provider being used can be seen here.

Note the infoblox.credentials option type and its use of the type OptionType.InputType.CREDENTIAL. The optionSource is critical as well as the list of possible credential types seen in the config block.

There are other credential types available that will be populated in this documentation later.

When making remote calls to the integration code it is important to reference the credential data correctly. For example, it is no longer simply a matter of referencing poolServer.serviceUsername or poolServer.servicePassword. Instead it is important to check the credentialData map on the AccountIntegration, Cloud, or NetworkPoolServer.

An example can be seen above where the credentialData is first checked.

As you can see, implementing unit and integration testing for your plugins can be done easily with Spock. Of course any other JVM unit testing framework should work as well.

Add custom Tasks types to Morpheus. See a full example.

Morpheus UI Extension Plugins provide a way to expand the capabilities of the Morpheus UI. Render custom content as a tab on an Instance, or even on a Server. Create a global injection component to the main layout footer for support/chat services. The possibilities are growing with each release and new functionality since 0.8.0 brings a lot. See a full tabs example.

See the Views section and the documentation for your templating engine for specific syntax.

It is becoming popular for some enterprises and managed service providers to expose simpler options when it comes to provisioning workloads. These could be used to target employees who are not highly technical or to further restrict what someone is allowed to order. Not only can they provision workloads like vms, and containers, but also execute operational tasks created by the administrator. Sometimes, it is necessary to further customize how a catalog detail page looks. There may be special ways of displaying information, or even the order form components need some advanced customization.

This plugin exposes the ability to control everything from the HTML used to render the catalog item, to the javascript that controls the form options. By default, we use a server-side handlebars template renderer however this can be completely customized if so desired.

Create custom report types for users to consume within Morpheus. Customize the behavior of how the report data is assembled and generated as well as the way it is rendered/displayed to the user. See a full example.

Integrate Morpheus with your own ITSM solution. See a full example.

The IPAM and DNS Provider Plugin interfaces provide an easy means to create direct orchestration for IP Address allocation/release as well as DNS Name server registrations. An IPAM Provider is often capable of implementing both interfaces as they often provide both services at once. It is also possible to independently register a DNSProvider only.

Both the DNS and IPAM Provider plugins typically consist of just 3 parts. First is defining the provider information such as the configuration options for adding the integration as well as pool types it offers. Secondly periodically syncing state data into morpheus back from the remote integration endpoints. This could include just syncing in available pools or zones, all the way to syncing in all IP host records or DNS zone records. This is up to your implementation.

The Cloud provider plugin interfaces are among the more complicated plugin types to implement within Morpheus, but when implemented successfully it provides a very powerful method for creating custom clouds or even updating existing cloud functionality. There are two primary concepts that must first be discussed when developing a cloud plugin.

A Cloud plugin typically defines a cloud type (you may see this as zoneType in api for legacy compatibility.) as well as at least one ProvisionProvider. A Provision Provider (also seen in api as provisionType) defines how a resource is provisioned within a cloud. A cloud could offer many provisioning types. For example, Amazon offers both EC2 as well as RDS.

There are several other provider implementations that are needed on more advanced cloud implementations and some are not yet built out. This includes NetworkProvider and BackupProvider implementations as well as a few more.

First we need to register the backup provider in the plugin

Creating a BackupPlugin involves registration of 2 types of providers: Backup Provider and Backup Type Provider.

The primary entry point into the plugin is the Backup Provider. The backup provider will handle all the high level operations within morpheus including creating and syncing the integration.

The example below is Backup provider is a single Backup Provider with multiple Backup Type Providers.

NOTE: The AbstractBackupProvider is convenient to avoid implementing standard methods and settings defined in the BackupProvider interface that are not used as often.

A Backup Type Provider MyVmwareBackupProvider is created and scoped by a provision type code. Adding a scoped provider will associate the provider to the provision type defined by the scoped provider. In the example a backup provider is defined for provisioning VMware instances.

All operations regarding the instance of a backup, including the creation and restoring of a backup, are handled by the BackupTypeProvider. A Backup Provider also can have many Backup Type Providers. For example some backup solutions can back up VMs on many cloud types and they each may have different relevant APIs.

The implementation from this point is flexible. The developer can choose to implement the execute and restore functionality directly in the backup type provider or in separate providers. The execute and restore providers are simply a way to organize the provider for clarity. There are various service interfaces provided for implementing the backup and restore behavior: BackupExecutionProvider, BackupRestoreProvider.

See the Rubrik Plugin for a full example implementation including execution and restore providers.

Like most other integrations, a periodic refresh method is called to sync in any necessary data the integration might need. It is recommended to use a SyncTask in these refresh methods which are optimized to handle blocking vs non-blocking thread scheduling.

A full backup provider implementation may not be required in many cases. The Morpheus Backup Provider can be used to handle all the high level operations. The example below would allow Morpheus to manage the backup job and delegate the backup execution and restore to back to the plugin’s Backup Type Providers.

See the DigitalOcean Plugin for a full example implementation of plugin that utilizes the Morpheus Backup Provider.