Structure of a plugin

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.

• logger: A standard Python Logger object.
• hook_point: A string naming the trigger point the action was called from. When the action is not running as an orchestration action, this is None.
• servers: An iterable of all servers the plugin targets. When there is only one, server is also available.
• resources: An iterable of all deployed resources the plugin targets. When there is only one, resource is also available.

What run() can return

A plugin’s run method returns either a tuple of three strings, or a dictionary. Use the dictionary form when you want to pass outputs to later steps.

Three-tuple returns

The tuple is (status, output, errors). On success, return ("", "", ""). If a non-empty status string is returned, the job engine saves the status, output, and errors to the job and skips any remaining steps. A pre-job plugin can use this to stop a job when its prerequisites are not met.

Dictionary returns

A dictionary return supports four optional keys:

• status: One of the valid status values below.
• output_message: The message returned on a successful run.
• error_message: The message highlighted in red on the job, drawing attention to the reason for the error.
• outputs: A dictionary of everything the plugin wants to hand on.

Valid status values

These are the status strings a plugin can return, with the text shown to the user on the job:

• SUCCESS: Completed successfully
• WARNING: Completed with warnings
• FAILURE: Completed with errors
• CANCELED: Canceled by user

Use outputs in a later step

When a plugin runs as a build step in a blueprint, later steps can reference what it returned with {{ outputs.<step name>.<key> }}, where <key> is a key from the dictionary the plugin returned. Use this in the code for later steps, or when setting default values for their action inputs.

<step name> is the build step’s name in lowercase, with spaces and dashes replaced by underscores and all other special characters removed, so that it forms a valid Python identifier.

Helpful methods

set_progress() both writes a message to the job’s detail page and adds a logging statement to that job’s log. Anything passed in the logger_kwargs dictionary is written as key/value pairs in the logging statement.

from common.methods import set_progress

set_progress(message, logger_kwargs={}, **kwargs)