Extensions overview

Since v7.0

Extensions are the plug-in mechanism for the MetalSoft platform. It allows 3rd party developers to extend the base functionality of MetalSoft in various ways such as:

Add deployable products (buttons) in the Infrastructure Designer
Add custom drivers for networking and server deployments
Execute custom code at pre or post-deploy
Integrate with DCIM systems or implement validation scripts

An extension consists of a definition file (extension.json — see the extension definition reference) and usually one or more assets: an Ansible bundle executed on the site controller and, optionally, a custom execution environment image.

Kinds of extensions

The kind is the third parameter of the extension create command:

application — adds a deployable product to the Infrastructure Designer, with a form, provisioned infrastructure and lifecycle playbooks. See App Extensions.
workflow — attaches tasks to platform events (server registered, DNS record changes, etc.). See Workflow extensions.
action — a flat list of tasks executed on demand, without stages.

Getting an extension working, end to end

At a high level, these are the pieces that must be in place for an extension to work:

The Ansible bundle — the playbooks and roles that do the actual work, zipped with the playbooks at the archive root and uploaded to an HTTP(S) repository reachable by the Global Controller. At runtime the platform generates the inventory and variables your playbooks consume. See Structuring Ansible bundles.
An OS template for the nodes (application extensions that deploy servers) — the template referenced by the extension’s instance arrays must exist at the target site and install the exact OS version the product requires (e.g. a specific ESX or Ubuntu build). Extensions can also build and mount custom ISOs on the target servers at deploy time (via the mount-and-boot mechanism) — this is how the OpenShift extension boots its agent-based installer image. See Managing OS templates.
An execution environment — the container image in which the site controller runs the extension’s Ansible tasks. All dependencies (Galaxy collections, Python modules, CLI tools) must be baked into it. Build it (e.g. with ansible-builder), push it to a registry reachable by the site controller, and either set it as the site default or attach it per task via an OciImage asset. See Execution environments.
Networks prepared in advance — the logical networks an application extension declares reference network profiles by label (infrastructure.logicalNetworks[].profileLabel); an operator must create a matching profile at every site where the extension will be deployed, or the deployment fails. See Infrastructure in the definition reference.
The extension definition (extension.json) — ties everything together: inputs render the form the user fills in and reach the playbooks as variables; outputs are values the playbooks return (URLs, credentials, kubeconfigs) that are stored and shown with the instance; configVars are operator-set, site-level values (e.g. DNS resolvers); all of them, plus the record set describing what was provisioned, arrive in the playbooks as extra-vars. See the extension definition reference and the runtime contract.
Creating the extension via the CLI — register the definition, publish it, and enable it per site (where configVars are also set). See the sections below for the commands.

Installing an extension

To install an extension use the CLI:

metalcloud-cli extension create my-workflow workflow "Custom deployment workflow" --definition-source extension.json

┌───┬───────┬─────────────┬────────┬──────────┬────────────────────────────┐
│ # │ LABEL │ NAME        │ STATUS │ KIND     │ DESCRIPTION                │
├───┼───────┼─────────────┼────────┼──────────┼────────────────────────────┤
│ 2 │       │ my-workflow │ draft  │ workflow │ Custom deployment workflow │
└───┴───────┴─────────────┴────────┴──────────┴────────────────────────────┘

The extension is created as draft and is not active until published. While it is in draft state it can be updated (metalcloud-cli extension update).

Activating an extension

An extension must be active before it can be used. To activate an extension use the CLI:

metalcloud-cli extension publish my-workflow

Note that for workflow extensions the extension must also be made public before it can be used, see below.

Making an extension public

metalcloud-cli extension make-public my-workflow

This controls the visibility of the extension:

For application extensions, extensions that are not public can be instantiated only by the owners of the extension.
For workflow extensions, all extensions must be made public before they can be used.

Archiving the extension

Note that it is not possible to update an extension that is active. To update an extension archive the old one and create a new one. This preserves information about extension instances and other information that might be required for billing purposes.

metalcloud-cli extension archive deprecated-workflow-v1

More information

For more information on building extensions follow: