Plugins on CloudBolt Documentation

Structure of a plugin

Mon, 01 Jan 0001 00:00:00 +0000

A plugin module must contain a function called run(). The Cloud Management Platform (CMP) job engine calls that function at particular points during a job’s execution.

What run() receives

The function is passed a Job object and a set of keyword arguments that simplify access to the CMP objects the plugin is likely to need. Every keyword argument below is passed to any plugin’s run method, but its value is None when the object it refers to does not apply in that context.

Special case plugins

Mon, 01 Jan 0001 00:00:00 +0000

Most plugins follow the shape described in Structure of a plugin. A few do not: they may run directly from the front-end appliance rather than inside a job, or they may have their own return types. Three are covered on this page; the rest are documented with the feature they belong to.

Order approval plugins: Replace the built-in approval workflow. Covered below.
Generate parameter options plugins: Decide a parameter’s options at run time. Covered below.
Auto-select environment plugins: Choose where a server tier is built. Covered below.
Order validation plugins: Run at the Blueprint Validation, Server Tier Validation, and Validate Order Recipient trigger points.
External user synchronization plugins: Run at the External Users Sync trigger point each time a directory user logs in.
Display condition plugins for server actions: Decide whether a server action’s button is shown.
Discovery plugins on blueprints: Onboard resources that were created outside Cloud Management Platform (CMP).

Order approval plugins

When an order approval plugin is enabled, it replaces Cloud Management Platform’s default behavior of emailing approvers when an order is submitted. Use one to integrate with a separate change management system, or to replace the standard approval workflow with something that fits your organization.

Development tips for plugins

Mon, 01 Jan 0001 00:00:00 +0000

Run remote scripts with connection info objects

Connection info objects let a plugin run scripts against systems that have no REST API. They are also the way to run commands remotely on Windows servers via WinRM or on Linux servers via SSH.

Windows servers

Create a connection info object and set its protocol to winrm.
In the CMP CLI (shell_plus), set the transport type. Supported types are ntlm, kerberos, credssp, and basic, depending on what the target requires.

from utilities.models import ConnectionInfo

connection_info = ConnectionInfo.objects.get(name='my_connection_info')
connection_info.transport = 'ntlm'
connection_info.save()

Linux servers

Create a connection info object and set its protocol to ssh.

Execute a script on the connection info host

This works for both Windows and Linux targets. The example shows every parameter execute_script accepts, with its default.

Plugin examples

Mon, 01 Jan 0001 00:00:00 +0000

CMP hosts a Content Library of example plugins, which you can import from most pages where actions are created, such as Server Actions and Orchestration Actions. The source for those plugins lives in a public GitHub repository.

Add a progress message

Use this at the Pre-Create Resource trigger point in a Provision Server job. It writes the server’s IP address to the job progress and log, then waits 60 seconds so the message is easy to notice.

Plugin parameterization

Mon, 01 Jan 0001 00:00:00 +0000

When you upload a plugin file or point at one by URL, CMP scans its contents for template variables such as {{ variable }} and creates an action input for each one it finds. See Action input parameters for more on generated inputs, and Action context for the objects available in each context.

CMP prompts users for those inputs and renders them into the action before it runs. Input values are escaped so they cannot execute arbitrary code while still rendering as expected.

Resources for writing plugins

Mon, 01 Jan 0001 00:00:00 +0000

Interact with the data model

Cloud Management Platform (CMP) has an interactive shell, allowing you to try a query before putting it in a plugin. Open an SSH session to the CMP appliance, switch to the root user, then start the shell_plus management command. It opens an interactive Python shell with all of the models already imported. From there you can work with them directly:

# Reboot the server with hostname "devtest0032"
server = Server.objects.get(hostname="devtest0032")
server.reboot()

# Re-assign all of David's servers to Lisa
lisa = UserProfile.objects.get(user__username='lisa')
Server.objects.filter(owner__user__username='david').update(owner=lisa)

# Get OS build attributes whose template name matches "ubuntu_16_sqaqe03_green".
# This filter is case insensitive, so it can return several results when
# template names differ only by capitalization.
rh = ResourceHandler.objects.get(id=11)
rh.os_build_attributes.filter(template_name__iexact='ubuntu_16_sqaqe03_green')

The internal API can be destructive, both to CMP and to the servers it manages. Do plugin development on a non-production instance that manages only development servers.

Use Django ORM

Mon, 01 Jan 0001 00:00:00 +0000

CMP’s models are exposed through Django’s object-relational mapper. Rather than looking up table and field names for SQL statements, you express create, read, update, and delete operations as Python, which makes them straightforward to script from a plugin or the interactive shell.

Queries become Python

For example, this SQL statement:

SELECT * FROM infrastructure_server;

becomes:

Server.objects.all()

Iterate results directly

Instead of loading a recordset from a database driver and stepping through it, you iterate the queryset with ordinary Python constructs.