Apache CloudStack 4.21 introduces the Extensions Framework, a lightweight and flexible mechanism that allows operators and developers to integrate external systems into CloudStack’s resource lifecycle management.

Traditionally, adding support for a new hypervisor, network plugin, or any other external system required deep changes to CloudStack’s core codebase. With the Extensions Framework, this complexity is reduced: you can now build an extension in any language or script, register it with CloudStack, and let it handle resource lifecycle actions externally—while CloudStack continues to manage the business logic such as ACLs, limits, usage, events, etc.

Why the Extensions Framework?

• Decoupling Lifecycle Logic

Lifecycle operations (like Instance create/start/stop/destroy) can be delegated to an external executable.

• Plug-and-Play Integrations

Extensions are executables that CloudStack invokes with action and JSON payload.

• Language Agnostic

Extensions can be written in Bash, Python, Go, Java, or any other programming language supported by Linux OS in the Management Server. From CloudStack perspective, it just needs to be an executable script or binary.

• Core Responsibilities Retained

CloudStack still tracks resources, enforces Limits, emits Events, generates Usage, Quota and provides the API/UI.

This makes it possible to integrate CloudStack with external hypervisors, network or storage plugins, authenticators or any other external systems without modifying CloudStack core.

 

Extension Types

Currently (CloudStack 4.21), the framework supports only Orchestrator-type Extensions, which are tied to Clusters. When a Cluster is associated with an Extension, CloudStack delegates Instance lifecycle Operations in that Cluster to the Extension.

Future scope: The framework is designed to be extensible. While today it supports only Orchestrator, in future it can be expanded to other areas such as:

• Networker – handle network lifecycle with external SDN or NFV systems.
• Authenticator – integrate with third-party identity/access systems for authentication.
• Storage – delegate storage provisioning and lifecycle to external storage backends.
• More types, as operator needs evolve.

This design ensures that CloudStack can grow into diverse infrastructures while keeping its API-driven, multi-tenant management consistent.

How Extensions Work

• A lifecycle event occurs for a resource (e.g., deploy an Instance).
• CloudStack first checks whether the resource is managed by an Extension. If it is, CloudStack invokes the Extension executable with the required parameters, passing a JSON payload containing resource details and a timeout:

<extension_path> <action> <payload_path> <timeout>

• The Extension reads the payload, performs operations against the external system, and writes a JSON result to stdout.
• CloudStack consumes the result, updates its DB, and continues handling Events, Usage, and Quotas.

Managing Extensions

Adding an Extension

To integrate an external system, an operator needs to create a new extension in CloudStack.

In the CloudStack UI, navigate to the Extensions section and click on Create Extension. This opens a form where you must provide key details such as:

• Name and Description
• Type (e.g., Orchestrator)
• Executable path (relative path)
• Configuration details (key/value pairs)
• Enabled state
• Any extension-type-specific parameters

The executable path should be relative, since all Extensions must reside under the following directory on all management servers:

/usr/share/cloudstack-management/extensions

Registering Extension with a Resource

After creating an Extension, it must be associated with a CloudStack resource so that it can handle operations and communicate with the external system.

For Orchestrator-type Extensions, the resource is a Cluster. You can register the extension with a cluster in either of the following ways:

• During Cluster creation – select the desired extension while creating the cluster.
• For an existing Cluster – open the cluster in the UI and use the Register Extension action from the extension view.

Once registered, all supported lifecycle operations for that cluster will be delegated to the extension.

Once an Extension is registered and enabled, it is ready to use. However, some Extension types may require additional setup before they can be used for resource deployment.

• For Orchestrator-type Extensions, the following steps are typically required before Instances can be deployed:
• Add a Host to the Cluster
  • The Cluster registered with the extension must contain at least one host.
  • This usually corresponds to a compute Host in the external system.
  • Host attributes such as name, URL, etc., can be placeholder (dummy) values, but operators can add configuration details in key–value format, which the extension script/executable can use to map or identify the host in the external system.

• Add a Template/ISO
  • Since Orchestrator extensions effectively represent a new hypervisor type, CloudStack requires Template/ISO entries to be added for them.
  • These entries should correspond to Templates/ISOs available in the external system.
  • Using the Register Template/ISO (for external images) action, operators can provide external details to help the extension match CloudStack entries with actual images.
• (Optional) Add Compute Offerings
  • New Compute Offerings can be created with external details if needed.
  • These offerings allow the extension to map CloudStack Offerings to equivalent Instance profiles in the external system.

Troubleshooting extensions

While the Extensions Framework is designed to keep the workflow simple and easy to use, Administrators may occasionally need to troubleshoot issues with an extension. A detailed troubleshooting guide is available in the CloudStack documentation.

At a high level, consider the following checks:

1. Verify presence on all management servers
   • Ensure the extension executable is present on all management servers.
   • CloudStack runs a periodic background task to verify the availability and consistency of extensions across servers.
   • The frequency is controlled by the global configuration parameter: path.state.check.interval
   • If inconsistencies are detected, CloudStack will report the Extension’s availability as Not Ready.
2. Check the extension’s state and configuration
   • Confirm the Extension is in Enabled
   • Ensure it has the required resources (e.g., Cluster, Hosts, Templates/ISOs).
   • Verify that configuration or external details (provided as key-value pairs) are set correctly.
3. Review management server logs

a) Look for errors or warnings in the CloudStack management server logs related to Extension execution.

4. Inspect the payloads

a) For every operation, CloudStack passes a structured JSON payload to the Extension binary.

b) These payloads are written to .json files under: /var/lib/cloudstack/management/extensions

c) Reviewing these files can help confirm what data CloudStack is sending to the extension.

Custom Actions for Extension

In addition to the standard lifecycle operations, CloudStack allows you to define Custom Actions for an Extension. These are Administrator-defined operations that extend the functionality of the Extension beyond basic resource management.

How Custom Actions Work

• A Custom Action must be implemented in the Extension’s script/executable.
• Like standard operations, CloudStack invokes the Extension executable with the action name and a structured JSON payload.
• The extension processes the payload and returns a JSON result to CloudStack.

Defining a Custom Action

When creating a Custom Action, Administrators can specify:

• Name and Description
• Parameters (with type and validation rules, improving end-user experience)
• Success and error messages
• Details (additional metadata)
• Timeout (to control execution duration)

Custom Actions for an Extension can be managed under the Custom Actions tab in the Extension view in the CloudStack UI.

Using Custom Actions

• All available Custom Actions for a resource are listed in the UI.
• Actions can be executed directly from the resource view.
• The UI also provides the ability to view the output returned by the Extension after the action completes.

 

Conclusion

The Extensions Framework makes Apache CloudStack much more flexible by offloading lifecycle operations to external systems while keeping the strong multi-tenant, API-driven, and quota-aware resource management intact.

Whether you need to integrate with a niche hypervisor, an in-house provisioning system, or add special actions, you can now do so with a simple script—without modifying CloudStack core.

While the framework in its current form has some limitations for Orchestrator Extensions, it represents the beginning of a larger vision. Future releases will expand both the framework and the set of built-in Extensions, enabling integrations across networking, authentication, storage, and beyond.

And if you’re looking to create a new extension, the documentation provides a detailed guide on writing extensions for CloudStack.