# XaaS blueprints

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

---

Site [llms.txt](/llms.txt)

---

Anything-as-a-Service blueprints call an external API to provision, delete, and manage a service. Users order it from the [Catalog](/docs/cmp/use/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](/docs/cmp/use/resources/resource-types/). 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](/docs/cmp/use/orchestration/actions/action-types/), 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](/docs/cmp/use/orchestration/actions/action-input-parameters/) | [Blueprint parameter](/docs/cmp/use/blueprints/customize-order-form/blueprint-level-parameters/) |
| --- | --- |
| Defined in the plugin. | Defined as a global parameter, then linked to the blueprint on its Parameters tab. |
| Its [constraints](/docs/cmp/configure/order-forms-and-pricing/parameters/parameter-options/#constraints) and option list belong to this action alone. | Its [defaults](/docs/cmp/configure/order-forms-and-pricing/parameters/parameter-options/#global-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](/docs/cmp/configure/order-forms-and-pricing/parameters/generated-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](/docs/cmp/configure/order-forms-and-pricing/parameters/parameter-options/#dependencies).

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](/docs/cmp/developer-resources/ui-extensions/) is another).

For a worked example, see [xaas_build.py](https://github.com/CloudBoltSoftware/hands-on-lab/blob/main/xaas_example/actions/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](https://github.com/CloudBoltSoftware/hands-on-lab/blob/main/xaas_example/actions/xaas_teardown.py).

### Management

Management plugins are [resource actions](/docs/cmp/use/orchestration/actions/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](https://github.com/CloudBoltSoftware/hands-on-lab/blob/main/xaas_example/actions/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](https://github.com/CloudBoltSoftware/hands-on-lab/blob/main/xaas_example/actions/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](/docs/cmp/use/orchestration/plugins/structure/). 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](/docs/cmp/developer-resources/ui-extensions/). |
| 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](/docs/cmp/developer-resources/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](/docs/cmp/configure/integrations/connection-info/) object and read them from your plugin. Do not put them in the plugin's code.

## Related

- [Resource types](/docs/cmp/use/resources/resource-types/): Creating the resource type an XaaS blueprint needs.
- [Plugins](/docs/cmp/use/orchestration/plugins/): Writing the plugins that run at each stage.
- [Deployment trigger points](/docs/cmp/developer-resources/guide/blueprints/deployment-trigger-points/): Running code at every deployment instead of on one blueprint.