Plugin Concepts

Terminology

Plugin code layout

Refers to organizing the different parts required to build a plugin as follows during developer design time:

Meta data file that contains plugin specific name, version, and description
Meta data file that contains procedure related parameters and UI related form elements
Procedure code implementation
Third Party Libraries
Promotion scripts
Setup scripts that go hand in hand with promotion
Help file documentation
The plugin icon

Plugin build

Refers to the process of building a plugin the output of which is a zip file.

Plugin provisioning and install

Refers to the process of exploding the zip file of the plugin on the server, including the expansion and merge of plugin metadata into an object structure in the file system and applying as an import to the CloudBees CD/RO RDBMS. After this step the plugin is still not usable until it is promoted.

Plugin promotion

Refers to the process of promoting a plugin version so it is usable, which among other things could include the import of the object structure created in install into the RDBMS and the creation of a plugin project whose name is a concatenation of the plugin key—a plugin’s unique identifier—and the version of the plugin. Where warranted, for example where there are no version conficts, installation is automatically followed by the promotion process. After this step the plugin is still not usable until it is configured, with the exception of plugins that do not have a configuration procedure defined. Since CloudBees CD/RO supports more than one version of a plugin to exist in the system, the logic for install/promotion is covered in a separate section below.

Plugin configuration

Refers to the process of setting up the plugin configuration procedure so it can be used. After this step the plugin is usable provided the integration with the third party does not expect the third party software to be co-located on the agent machine. Otherwise the agent setup below should be performed. The point to note is that after a plugin configuration has been performed it does not mean the plugin is necessarily usable.

Plugin agent setup

Refers to the process of making sure that the agent is co-located with the third party software, where this is warranted. For example a plugin that is implemented using a Rest API integration with the third party does not require this setup, whereas a plugin that is implemented using a CLI integration might. In addition the agent resource information which runs the commands in the procedure step, should be registered in the server.

Plugin runtime shell

Refers to the program that executes the commands in a procedure step, on the agent. Typically the commands are in a scripting language and the Shell an interpreter that can execute that language. In this sense the runtime shell ties back to a programming language. Currently there are two runtime shells supported for plugins--ec-perl and ec-groovy.

Plugin publish to catalog

Refers to an internal process in where a tested plugin gets published to a catalog. After being published, a plugin can be downloaded directly from a website or using the View Catalog functionality in the .

Concepts

Plugin metadata

The following snippet from plugin.xml provides the salient metadata of a plugin that pertains to its identity, compatibility with versions, and its support level. Note the following:

The plugin key represents a unique system identifier that is used internally by build, install and promotion processes.
The plugin label represents the user friendly name of the plugin key that can be typically used in a UI. It has the flexibility to be changed.
The @ symbols provided here are wild cards which get resolved when the plugin gets built.

<plugin>
<key>@PLUGIN_KEY@</key>
<version>@PLUGIN_VERSION@</version>
<label>@PLUGIN_KEY@</label>
<description>WebLogic Application Server</description>
<configure>configurations.xml</configure>
<help>EC-WebLogic_help.xml</help>
<author>CloudBees</author>
<authorUrl>http://www.electric-cloud.com/support</authorUrl>
<category>Application Server</category>
<commander-version min="3.6"/>
<components>
    <component name="ConfigurationManagement">
        <javascript>war/ecplugins.weblogic.ConfigurationManagement/ecplugins.weblogic.ConfigurationManagement.nocache.js</javascript>
    </component>
</components>
</plugin>▼

Plugin versioning

Plugins use a version nomenclature of the form X.Y.Z.W and as follows:

X— major version, Y— minor version, Z— patch version, `W — build version.
Major releases normally include significant new features, support only a certain version of CloudBees CD/RO, or have changes that are not backward compatible.
Minor releases may include fixes and new features.
Patch (maintenance) releases only include bug fixes.
Build version basically increments the counter for a given major, minor and patch version, during the development cycle as new builds get created.

Install and promotion logic

Plugin versions play an important role in the installation and promotion of a plugin version. These are general principles that govern promotion of a plugin version.

A plugin with either a higher major or minor version (than an already existing plugin) is installed but not promoted.
A plugin with higher patch version and the same major and minor version as an already existing plugin is installed and promoted, after uninstalling the existing plugin.
A plugin with higher build version and the same major, minor, and patch version (as an already existing plugin) will get installed and promoted, after uninstalling the existing plugin.

The following table is provided for further clarity. Assume the following:

A = X.Y.Z.W = Version of existing plugin in the system.
B = X1.Y1.Z1.W1 = Version of plugin to be installed.

CASES OUTCOME

CASES	OUTCOME
`X1` > `X`	`B` is installed, not promoted. `A` exists and not overwritten. `A` remains as the active version, until demoted and `B` is promoted.
`X1` = `X` and `Y1` > `Y`	Same as above.
`X1` = `X`, `Y1` = `Y` and `Z1` > `Z`	`A` is uninstalled. `B` is installed and promoted.
`X1` = `X`, `Y1` = `Y`, `Z1` = `Z` and `W1` > `W`	Same as above.

X1 > X

B is installed, not promoted. A exists and not overwritten. A remains as the active version, until demoted and B is promoted.

X1 = X and Y1 > Y

Same as above.

X1 = X, Y1 = Y and Z1 > Z

A is uninstalled. B is installed and promoted.

X1 = X, Y1 = Y, Z1 = Z and W1 > W

Same as above.

Architecture

Content

A plugin is characterized by its metadata and by the project that encapsulates its features and exposes them as procedures. The plugin project is like a project, but whose name is suffixed by the version of the plugin.

Install

The diagram below represents the details of what happens in a plugin install. The key point to note is that the install entails uploading all objects required at runtime, to the RDBMS or the filesystem as required.

Promotion

The diagrams below represent what a plugin promotion entails. The key point is that only one version of a plugin can be active/functional at a time.

The first diagram shows an upgrade where in a higher version gets promoted after the lower version is demoted.
The second diagram shows a downgrade, where in a lower version gets promoted after the higher version gets demoted. Note that the downgrade scenario in the second diagram is typically performed manually where such a situation is warranted.

Procedure structure

A plugin procedure consists of one or more steps, each executing on a CloudBees CD/RO agent resource. Where necessary, different steps can run on different agents.

Procedure step execution

The diagram below represents the typical flow of execution in a plugin. There are two key points to note:

The various parameter values at runtime required by a procedure step can come from anywhere in the execution Hierarchy.
The framework provides the APIs required to perform all the operations mentioned below.