XaaS blueprints

Use XaaS blueprints to create Catalog entries for services Cloud Management Platform (CMP) does not natively support

  5 minute read  

Anything-as-a-Service blueprints call an external API to provision, delete, and manage a service. Users order it from the Catalog the same way they order a server. You define what happens at each stage, while CMP handles the catalog, order form, approvals, and auditing.

Start by giving the service a custom resource type. This is what holds the deployment’s parameters and gives day-2 operations something to attach to.

Lifecycle

Develop these in order. Build is what makes the service orderable. Without teardown, deleting a resource in CMP leaves the real service running at the provider.

Stage Blueprint tab What your code does
Provision Build Creates the service and records what it created.
Deprovision Teardown Deletes the service and cleans up after it.
Day-2 operations Management Optional. Changes the service, such as resizing or restarting it.
Discovery Discovery Optional. Imports existing services so users can manage them here.

Build

The build stage can use any action type, but a new service usually keeps all its logic in a single plugin.

A plugin on a blueprint takes its input in one of two ways:

Action input Blueprint parameter
Defined in the plugin. Defined as a global parameter, then linked to the blueprint on its Parameters tab.
Its constraints and option list belong to this action alone. Its defaults, constraints, and options are shared by every blueprint that uses it.
Options can be generated inside the plugin with a generate_options_for_ method. Options come from a separate plugin attached to the parameter. See Generated parameter options.
Appears on a later tab of the order form. Appears on the first tab of the order form.

Both kinds can depend on other fields.

Use action inputs for service-specific details and blueprint parameters for organizational details, such as a cost center or business unit. Action inputs get their own tab, so moving an input to a blueprint parameter is one way to refine a form with many tabs (a custom order form built as a UI extension is another).

For a worked example, see xaas_build.py in the hands-on lab.

Teardown

Teardown deletes the service and anything it created. It is usually a single plugin.

Example: xaas_teardown.py.

Management

Management plugins are resource actions that appear as buttons on the resource’s page. They are how a user resizes, restarts, or reconfigures the service.

Example: xaas_resource_action.py.

Discovery

A discovery plugin finds services that CMP did not deploy, imports them, syncs their state, and exposes the resource actions. It runs as part of the Sync Resources recurring job, so that job must be enabled for discovery to occur.

Example: xaas_discovery.py.

What the plugin has to do

An XaaS plugin uses the same run(job, **kwargs) entry point as described in Structure of a plugin. The difference is that it creates an instance of the new service, something CMP did not build and cannot see, so it also has to record enough to find that service again.

What to store, and where

Decide for each piece of information whether CMP holds it and whether a user sees it.

Information type Example Where it lives
The name users know it by Resource name resource.name. Collected on the order form and usually sent to the provider as the service’s name.
The provider’s identifier UUID, instance ID, GUID A resource parameter. Read it back from the provider at creation time and store it; all subsequent operations depend on it.
Specification Disk size, cluster size Resource parameters, since you sent these values to the provider and they change only when someone changes them.
Runtime status Utilization percentage Not stored. Read it live and show it on a resource tab UI extension.
Secrets the user needs Access key Not stored. Prefer a service that the user reaches with their own credentials. If they must come from CMP, fetch and show them on demand.
Secrets CMP needs Certificate An encrypted resource parameter, when management actions need it to act on the user’s behalf.
Which environment it belongs to CMP environment resource.environment_id. Optional, and useful for logical resource separation.

Showing information to users

There are two places where service information can appear, depending on how often it changes.

  • Resource parameters are stored in the CMP database. For values that are fixed, or that CMP is the source of truth for. Turn on Show as Attribute on the parameter to surface it on the resource’s page.
  • Resource tab UI extensions read from the provider as the page loads. For anything that changes on its own, such as the number of messages waiting in a queue.

A stored parameter is refreshed only when the Sync Resources recurring job runs, but it can be shown in resource lists and reported on. A UI extension is always up to date but exists only on that tab.

Credentials for the API

If the service is not already accessible via a resource handler or another configured integration, store its credentials as a Connection Info object and read them from your plugin. Do not put them in the plugin’s code.