Extensions

Extensions are a new mechanism introduced in Apache CloudStack to allow administrators to extend the platform’s functionality by integrating external systems or custom workflows. Currently, CloudStack supports a single extension type called Orchestrator.

In the UI, extensions can be managed under Extensions menu.

Overview

An extension in CloudStack is defined as an external binary (written in any programming language) that implements specific actions CloudStack can invoke. This allows operators to manage resource lifecycle operations outside CloudStack, such as provisioning VMs in third-party systems or triggering external automation pipelines.

Extensions are managed through the API and UI, with support for configuration, resource mappings, and action execution.

Configuration

Administrators can define and manage the following components of an extension:

Path: A path to a file or script that will be executed during extension operations.

Configuration Details: Key-value properties used by the extension at runtime.

Resource Mappings: Association between extensions and CloudStack resources such as clusters, etc.

Path and Availabilty

The path for an extension can point to any binary or executable script. If no explicit path is provided, CloudStack uses a default base Bash script. The state of the path is validated across all management servers. In the UI, the Availabilty is displayed as Not Ready if the file is missing, inaccessible, or differs across management servers.

All extension files are stored under a directory named after the extension within /usr/share/cloudstack-management/extensions.

Payload

CloudStack sends structured JSON payloads to the extension binary during each operation. These payloads are written to .json files stored under /var/lib/cloudstack/management/extensions. The extension binary is expected to read the file and return an appropriate result. CloudStack automatically attempts to clean up payload files older than one day.

Orchestrator Extension

An Orchestrator extension enables CloudStack to delegate VM orchestration to an external system. Key features include:

Cluster Mapping: Orchestrator extensions can be associated with one or more CloudStack clusters.

Hosts: Multiple hosts can be added to such clusters, ideally pointing to different physical or external hosts.

Instance Lifecycle Support: Extensions can handle basic VM actions like prepare, deploy, start, stop, reboot, status and delete.

Configuration Details: Key-value configuration details can be specified at different levels - extension, cluster mapping, host, template, service offering, instance.

Custom Actions: Admins can define custom actions beyond the standard VM operations.

Instance Preparation: Orchestrator extensions can optionally perform a preparation step during instance deployment. This step is executed before the instance is started on the external system. It allows the extension to update certain instance details in CloudStack. CloudStack sends a structured JSON containing the instance configuration, and the extension can respond with the values it wishes to modify. Currently, only a limited set of fields can be updated: the instance’s VNC password, MAC address, details, and the IPv4/IPv6 addresses of its NICs.

Networking: If networking is setup properly on the external system (See inbuilt extensions networking for more details.), the Virtual Router in CloudStack can connect to the external VMs and provide DHCP, DNS, and routing services.

Note: User data and ssh-key injection from within CloudStack is not supported for the external VMs in this release. The External systems should handle user-data and ssh-key injections natively using other mechanisms.

CloudStack provides sample inbuilt orchestrator extensions for demonstration and testing purposes.

Note

When a CloudStack host linked to an orchestrator extension is placed into Maintenance mode, all running instances on the host will be stopped.
For hosts linked to extensions, CloudStack will report zero for CPU and memory capacity, and host metrics will reflect the same. During instance deployment, capacity checks are the responsibility of the extension executable; CloudStack will not perform any capacity calculations.
Some of the features that rely on interaction with VMs, such as VM snapshots, live migration, VM scaling, VM autoscaling groups, VNF appliance, Kubernetes clusters, etc are currently not supported for instances managed by orchestrator extensions.

Custom Actions

In addition to standard instance operations, extensions support custom actions. These can be configured via UI in the extension details view or the addCustomAction API. The extension binary or script must implement handlers for these action names and process any provided parameters.

Description, allowed role types, parameters, success/error messages, configuration details, timeout can be defined during creation or update. Alowed role types can be one or more of Admin, Resource Admin, Domain Admin, User. Success and error messages will be used and returned during action execution. They allow string expansion and the following can be used to customise messages:

{{actionName}} for showing name of the action

{{extensionName}} for showing name of the extension

{{resourceName}} for showing name of the resource

An example usage can be - “Successfully completed {{actionName}} for {{resourceName}} using {{extensionName}}”. Configuration details can be key-value pairs which will be passed to the extension during action execution. Timeout value can be configured to adjust wait time for action completion.

A single parameter can have the following details:

name: Name of the parameter.

type: Type of the parameter. It can be one of the following: BOOLEAN, DATE, NUMBER, STRING

validationformat: Validation format for the parameter value. Supported only for NUMBER and STRING type. For NUMBER, it can be NONE or DECIMAL. For STRING, it can be NONE, EMAIL, PASSWORD, URL, UUID.

valueoptions: Options for the value of the parameter. This is allowed only for NUMBER and STRING type.

Running Custom Action

All enabled custom actions can then be triggered for a resource of the type the action is defined for or provided while running, using the Run Action view or runCustomAction API.

Troubleshooting Extensions

Validate the Extension Path

Ensure that the path is correctly defined and accessible on all management servers. The executable must be owned by the cloud user and group, and have appropriate permissions to be executed by cloud:cloud.

The script or binary must be executable and have appropriate permissions.

If the binary differs across management servers, the extension will be marked as Not Ready.

Ensure files are stored at: /usr/share/cloudstack-management/extensions/<extension_name>

CloudStack runs a background task at regular intervals to verify path readiness. If the path is not ready, its state will appear as Not Ready in the UI or API responses.

Alerts are generated if the extension path is not ready.

The check interval can be configured using the global configuration - extension.path.state.check.interval. The default is 5 minutes.

Verify Payload Handling

Ensure the extension binary can correctly read and parse the incoming JSON payload.

Payload files are placed at: /var/lib/cloudstack/management/extensions/<extension_name>/

These payload files are automatically cleaned up after 24 hours.

Improper parsing of the payload is a common cause of failure—log any parsing errors in your extension binary for debugging.

Refer to Base Extension Scripts

For guidance on implementing supported actions, refer to the base scripts present for each extension type.

For Orchestrator-type extensions, see: /usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh

These scripts provide examples of how to handle standard actions like start, stop, status, etc.

Check Logs for Errors

If the extension does not respond or returns an error, check the management server logs.

Logs include details of:

Invocation of the extension binary

Payload hand-off

Output parsing

Any exceptions or exit code issues.

Writing Extensions for CloudStack

The CloudStack Extensions Framework allows developers and operators to write extensions using any programming language or script. From CloudStack’s perspective, an extension is simply an executable capable of handling specific actions and processing input payloads. CloudStack invokes the executable by passing the action name and the path to a JSON-formatted payload file as command-line arguments. The extension processes the payload, performs the required operations on an external system, and returns the result as a JSON response written to stdout.

Create a New Extension

You must first register a new extension using the API or UI:

cloudmonkey createExtension name=myext path=myext-executable

Arguments:

name: Unique name
path: Relative path to the executable. Root path will be /usr/share/cloudstack-management/extensions/<extension_name>

The path must be:

Executable (chmod +x)
Owned by the cloud:cloud user
Present on all management servers (identical path and binary)

If no explicit path is provided during extension creation, CloudStack will scaffold a basic shell script at a default location with minimal required action handlers. This provides a starting point for customization and ensures the extension is immediately recognized and callable by the system.

CloudStack checks extension readiness periodically and shows its state in the UI/API.

Extension Structure

Your extension must support the following invocation structure:

/path/to/executable <action> <payload_file> <timeout_seconds>

Arguments:

<action>: Action name (e.g., deploy, start, status)
<payload_file>: Path to the input JSON file
<timeout_seconds>: Max duration CloudStack will wait for completion

Sample Invocation:

/usr/share/cloudstack-management/extensions/myext/myext.py deploy /var/lib/cloudstack/management/extensions/myext/162345.json 60

Input Format (Payload)

CloudStack provides input via a JSON file, which your executable must read and parse.

Example:

{
  "externaldetails": {
    "resourcemap": {
      ...
    },
    "virtualmachine": {
      "exttemplateid": "1"
    },
    "host": {
      ...
    },
    "extension": {
      ...
    }
  },
  "virtualmachineid": "...",
  "cloudstack.vm.details": {
    "id": 100,
    "name": "i-2-100-VM",
    ...
  },
  "virtualmachinename": "i-2-100-VM"
}

The schema varies depending on the resource and action. Use this to perform context-specific logic.

Output Format

Your extension should write a response JSON to stdout. Example:

{
  "status": "success",
  "message": "Deployment completed"
}

For custom actions, CloudStack will display the message in the UI if the output JSON includes "printmessage": "true". The message field can be a string, a JSON object or a JSON array.

Action Lifecycle

A CloudStack action (e.g., deploy VM) triggers a corresponding extension action.
CloudStack invokes the extension’s executable with appropriate parameters.
The extension processes the input and responds within the timeout.
CloudStack continues orchestration based on the result.

Custom Actions

You can define new custom actions for users or admin-triggered workflows.

Register via UI or addCustomAction API
Define input parameters (name, type, required)
Implement the handler for the custom action in your executable.

CloudStack UI will render forms dynamically based on these definitions.

Best Practices

Make executable/script idempotent and stateless
Validate all inputs before acting
Avoid hard dependencies on CloudStack internals
Implement logging for troubleshooting
Use exit code and stdout for signaling success/failure

Extension Examples

Bash Example

#!/bin/bash
ACTION=$1
FILE=$2
TIMEOUT=$3

if [ "$ACTION" == "deploy" ]; then
    echo '{ "success": true, "result": { "message": "OK" } }'
else
    echo '{ "success": false, "result": { "message": "Unsupported action" } }'
fi

Python Example

import sys, json

action = sys.argv[1]
payload_file = sys.argv[2]

with open(payload_file) as f:
    data = json.load(f)

if action == "deploy":
    print(json.dumps({"success": True, "result": {"message": "Deployed"}}))
else:
    print(json.dumps({"success": False, "result": {"message": "Unknown action"}}))

For a clearer understanding of how to implement an extension, developers can refer to the base shell script scaffolded by CloudStack for orchestrator-type extensions. This script is located at:

/usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh

It serves as a template with minimal required action handlers, making it a useful starting point for building new extensions.

Additionally, CloudStack includes built-in extensions for Proxmox and Hyper-V that demonstrate how to implement extensions in different languages - Bash and Python.