Developer Task: Creating Custom Plugins

7 minute read

CloudBees CD uses third-party plugins to provision cloud resources in resource templates for Dynamic Environments. Amazon EC2 (EC-EC2) and OpenStack (EC-OpenStack) are supported as out-of-the-box cloud provider plugins, and Chef (EC-Chef) is supported as an out-of-the-box configuration management plugin.

To view the supported cloud provider plugins, open the New Cloud Provider dialog box and click Select cloud provider to view the drop-down menu of cloud providers.

oob cloud prov

To view the supported configuration management plugins, click Select configuration management to view the drop-down menu of configuration management tools.

oob config mgmt

If you have an existing procedure that you would prefer to use instead of an out-of-the-box third-party plugin to provision cloud resources, you can create a custom plugin based on your deployment scenario.

The process to create custom cloud provider and configuration management plugins uses metadata to loosely couple them to the application you want to deploy. The custom plugins define specific known properties that are automatically recognized by Dynamic Environments.

To create your own plugin for other cloud platforms, see https://electric-cloud.github.io/index.html to get started. This website describes how to create open source plugins and has this information:

Creating Custom Cloud Provider Plugins

This section applies to developers who want to create custom cloud provider plugins for Dynamic Environments in CloudBees CD.

How to Create a Custom Cloud Provider Plugin

This procedure assumes that you already have a plugin and want to use it with CloudBees CD. It describes how to define properties in your plugin that CloudBees CD can read.

  1. To convert your procedure to a plugin, define the name of the plugin and the CloudBees CD project to which the plugin belongs.

    Later in this procedure, you will use these properties to create pre- and post-hooks to the plugin in CloudBees CD.

  2. Define the following properties in your plugin under a top-level plugin property called ` ec_cloudprovisioning_plugin`, which the system will read to Dynamic Environments.

    Property Name Description

    ec_cloudprovisioning_plugin/

    Top-level plugin property directory

    Properties defined by the custom plugin under ec_cloudprovisioning_plugin

    ` displayName`

    Name of the plugin that appears in the New Cloud Provider dialog box.

    Example: Amazon for the EC-EC2 plugin

    hasConfiguration

    <Boolean flag — 0|1|true|false >

    • Set this property to 0 if the plugin does not have any configuration procedures ( CreateConfiguration and DeleteConfiguration ).

    • Set this property to 1 if the plugin has configuration procedures.

    configurationLocation

    Name of the property sheet used by the plugin to store the saved configurations.

    This value is relative to the plugin’s top-level properties. For example, if this value is set as ec2_cfgs , the plugins configurations are read from /plugins/<PLUGIN_KEY>/project/ec2_cfgs .

    operations/

    Property sheet for the specific operations required by the Dynamic Environment system.

    Properties under operations/ – These operations are mapped to the plugin operations through the following child properties.

    createConfiguration/

    Properties for the procedure that creates the plugin configuration. It is usually called ` createConfiguration`.

    deleteConfiguration/

    Properties for the procedure that deletes the plugin configuration. It is usually called ` deleteConfiguration`.

    provision/

    Properties for the procedure that provisions virtual instances.

    retireResource/

    Properties for the procedure that tears down (decommissions) a previously provisioned virtual instance backing the specified resource.

    retireResourcePool/

    Properties for the procedure that tears down (decommissions) all previously provisioned virtual instances for the specified resource pool.

    Properties for the previously listed operations defined in the operations property sheet

    procedureName

    Name of the procedure name in the plugin to which the operation is mapped.

    ui_formRefs/

    Property sheet that references the ui_forms properties defined under the plugin’s top-level properties.

    parameterRefs/

    Property sheet for the input parameters to the procedure that can be used by the Dynamic Environment system.

    The parameter list is operation-specific.

    See Example: Property Structure for a Cloud Provider Plugin for an example of the properties for the EC-EC2 (Amazon) plugin.

  3. Save the plugin file in the appropriate location on your CloudBees CD server.

  4. To import the plugin file to the automation platform:

    1. In the automation platform, go to Administration > Plugins to open the Plugin Manager page.

    2. Click the Install from File/URL tab.

    3. In the File Install field, click Choose file to select the plugin file.

    4. Click Upload to install it.

      The plugin file appears in the Currently Installed tab.

    5. Find your plugin and click Promote in the Actions column to make it available for use by CloudBees CD.

  5. In CloudBees CD, to create a resource template:

    1. See Creating Resource Templates for the details.

    2. In the Select cloud provider field, select your plugin as the cloud provider.

    3. Enter the plugin settings in the form.

    4. (Optional) Set the configuration management tool.

      See Creating Resource Templates for the details.

  6. In the ectool API, enter the following commands to set pre- and post-hooks linking the plugin to an application that you later deploy in a dynamic environment.

    1. To create a pre-hook, enter

      ectool createHook postConfigurationHook --hookType POST_CONFIGURATION --procedureName <hookProcedureName> --procedureProjectName <hookProjectName> --resourceTemplateName <resourceTemplateName> --projectName <resourceTemplateProjectName>

      where hookProcedureName is the plugin procedure name, hookProjectName is the name of the project to which the plugin procedure belongs, resourceTemplateName is the name of the resource template you created, and resourceTemplateProjectName is the name of the project to which the resource template belongs.

    2. To create a post-hook, enter

      ectool createHook preConfigurationHook --hookType PRE_CONFIGURATION --procedureName <hookProcedureName> --procedureProjectName <hookProjectName> --resourceTemplateName <resourceTemplateName> --projectName <resourceTemplateProjectName>

      where hookProcedureName is the plugin procedure name, hookProjectName is the name of the project to which the plugin procedure belongs, resourceTemplateName is the name of the resource template you created, and resourceTemplateProjectName is the name of the project to which the resource template belongs.

  7. Create an environment template with the resource template that you created.

Example: Property Structure for a Cloud Provider Plugin

This is the EC-EC2 (Amazon) plugin property structure.

Property Name Property Values

ec_cloudprovisioning_plugin/

` displayName`

Amazon

hasConfiguration

1

configurationLocation

ec2_cfgs

operations/

createConfiguration/

deleteConfiguration/

provision/

retireResource/

retireResourcePool/

ec_cloudprovisioning_plugin/createConfiguration/

procedureName

CreateConfiguration

ui_formRefs/

ui_formRefs/parameterForm

ui_forms/EC2CreateConfigForm

parameterRefs/

parameterRefs/ configuration

config

ec_cloudprovisioning_plugin/deleteConfiguration/

procedureName

DeleteConfiguration

ui_formRefs/

parameterRefs/

configuration called config

ec_cloudprovisioning_plugin/provision/

procedureName

API_RunInstances

ui_formRefs/

parameterForm called ec_parameterForm

parameterRefs/

configuration called config

resourcePool called res_poolName

count called count

ec_cloudprovisioning_plugin/retireResource/

procedureName

API_TearDownResource

ui_formRefs/

parameterRefs/

resourcePool called res_poolName

ec_cloudprovisioning_plugin/retireResourcePool/

procedureName

API_TearDownResource

` ui_formRefs/`

parameterRefs/

resourcePool called res_poolName

Creating Custom Configuration Management Plugins

This section applies to developers who want to create custom configuration management plugins for Dynamic Environments in CloudBees CD.

How to Create a Custom Configuration Management Plugin

This procedure assumes that you already have a plugin and want to use it with CloudBees CD. It describes how to define properties in your plugin that CloudBees CD can read.

  1. To convert your procedure to a plugin, define the name of the plugin and the CloudBees CD project to which the plugin belongs.

    Later in this procedure, you will use these properties to create pre- and post-hooks to the plugin in CloudBees CD.

  2. Define the following properties in your plugin under a top-level plugin property called ` ec_configurationmanagement_plugin`, which the Dynamic Environment system can access.

    Name Description

    ec_configurationmanagement_plugin/

    Top-level plugin property directory

    Properties defined by the custom plugin under ec_configurationmanagement_plugin

    displayName

    Name of the plugin that appears in the Dynamic Environment UI

    Example: Chef for the EC-Chef plugin

    hasConfiguration

    <Boolean flag — 0|1|true|false >

    • When this property is set to 0 or false, the plugin does not have any configuration procedures ( CreateConfiguration and DeleteConfiguration ).

    • When this property is set to 1 or true, the plugin has configuration procedures.

    configurationLocation

    Name of the property sheet used by the plugin to store the saved configurations.

    This value is relative to the plugin’s top-level properties.

    If this value is set as chef_cfgs , the configurations are in /plugins/<PLUGIN_KEY>/project/chef_cfgs .

    operations/

    Property sheet for the specific operations required by the Dynamic Environment system.

    Properties under operations/ – These operations are mapped to the plugin operations through the following child properties.

    createConfiguration/

    Properties for the procedure that creates the plugin configuration. It is usually called ` createConfiguration`.

    deleteConfiguration/

    Properties for the procedure that deletes the plugin configuration. It is usually called ` deleteConfiguration`.

    converge/

    Properties for the procedure that converges the virtual instances to the defined configuration (including policies and roles).

    teardown/

    Properties for the procedure that deletes the configuration details on the specified dynamic resource or resource pool.

    For Chef, properties for the procedure that deletes the Chef API client and Chef node on the specified dynamic resource or resource pool.

    Properties for the previously listed operations defined in the operations property sheet

    Properties for the previously listed operations defined in the operations property sheet

    procedureName

    ui_formRefs/

    Property sheet that references the ui_forms properties defined under the plugin’s top-level properties.

    parameterRefs/

    Property sheet for the input parameters to the procedure that can be used by the Dynamic Environment system.

    The parameter list is operation-specific.

    See Example: Property Structure for a Configuration Management Plugin for an example of the properties for the EC-Chef plugin.

  3. Save the plugin file in the appropriate location on your CloudBees CD server.

  4. To import the plugin file to the automation platform:

    1. In the automation platform, go to Administration > Plugins to open the Plugin Manager page.

    2. Click the Install from File/URL tab.

    3. In the File Install field, click Choose file to select the plugin file.

    4. Click Upload to install it.

      The plugin file appears in the Currently Installed tab.

    5. Find your plugin and click Promote in the Actions column to make it available for use by CloudBees CD.

  5. In CloudBees CD, to create a resource template:

    1. See Creating Resource Templates for the details.

    2. In the Select cloud provider field, select a cloud provider.

    3. Enter the account settings for the selected cloud provider.

    4. Enter the provision parameters on the next page.

    5. In the Select configuration management field, select your plugin as the configuration management tool.

      See Creating Resource Templates for the details.

  6. In the ectool API, enter the following commands to set pre- and post-hooks linking the plugin to an application that you later deploy in a dynamic environment.

    1. To create a pre-hook, enter

      ectool createHook postConfigurationHook --hookType POST_CONFIGURATION --procedureName <hookProcedureName> --procedureProjectName <hookProjectName> --resourceTemplateName <resourceTemplateName> --projectName <resourceTemplateProjectName>

      where hookProcedureName is the plugin procedure name, hookProjectName is the name of the project to which the plugin procedure belongs, resourceTemplateName is the name of the resource template you created, and resourceTemplateProjectName is the name of the project to which the resource template belongs.

    2. To create a post-hook, enter

      ectool createHook preConfigurationHook --hookType PRE_CONFIGURATION --procedureName <hookProcedureName> --procedureProjectName <hookProjectName> --resourceTemplateName <resourceTemplateName> --projectName <resourceTemplateProjectName>

      where hookProcedureName is the plugin procedure name, hookProjectName is the name of the project to which the plugin procedure belongs, resourceTemplateName is the name of the resource template you created, and resourceTemplateProjectName is the name of the project to which the resource template belongs.

  7. Create an environment template with the resource template you created.

Example: Property Structure for a Configuration Management Plugin

This is the EC-Chef plugin property structure.

Name Values

ec_configurationmanagement_plugin/

` displayName`

Chef

hasConfiguration

1

configurationLocation

chef_cfgs

operations/

createConfiguration/

deleteConfiguration/

converge/

teardown/

ec_configurationmanagement_plugin/createConfiguration/

procedureName

CreateConfiguration

ui_formRefs/

parameterForm called forms/CreateConfigForm

parameterRefs/

configuration called config

ec_configurationmanagement_plugin/deleteConfiguration/

procedureName

DeleteConfiguration

ui_formRefs/

parameterRefs/

configuration called config

ec_configurationmanagement_plugin/converge/

procedureName

_RegisterAndConvergeNode

ui_formRefs/

parameterForm called ec_parameterForm

parameterRefs/

configuration called config

ec_cloudprovisioning_plugin/teardown/

procedureName

_DeleteNode

ui_formRefs/

parameterRefs/

resourceName called resource_name