With the introduction of the Extensions Framework in Apache CloudStack 4.21, CloudStack gained a structured and extensible way to integrate external orchestrators into its resource lifecycle management. The framework is designed to allow CloudStack to delegate provisioning and lifecycle operations to external systems without embedding that logic into the core platform.

This approach enables CloudStack to orchestrate resources that are not natively managed by its internal hypervisor abstractions. These can include alternative virtualisation stacks, specialised infrastructure components, and bare metal provisioning systems, all integrated through a consistent operational model.

Building on this foundation, CloudStack 4.22 introduces bare metal provisioning through integration with Canonical MAAS (Metal-as-a-Service). As a concrete example of what the Extensions Framework enables, the MAAS integration allows physical servers to be provisioned and managed alongside Virtual Machine Instances using the same CloudStack workflows and user interface.

About Canonical MAAS

Canonical MAAS (Metal-as-a-Service) is a bare metal provisioning and lifecycle management platform designed to treat physical servers as first-class infrastructure resources. It provides automated discovery, commissioning, operating system deployment, and power management for physical machines, using standard mechanisms such as PXE boot and out-of-band management (for example, IPMI or Redfish).

MAAS manages hardware inventory, images, and network configuration centrally, allowing operators to allocate and release physical servers on demand. Once a machine is deployed, MAAS continues to track its state and can perform actions such as reboot, power off, redeploy, or release the server back into the available pool.

This model makes MAAS suitable for environments where physical infrastructure must be provisioned dynamically, including edge locations, hardware testing and validation labs, and high-performance computing (HPC) clusters.

When integrated with Apache CloudStack through the Extensions Framework, MAAS acts as the underlying bare metal orchestrator. CloudStack delegates lifecycle operations to MAAS via its REST APIs, while retaining responsibility for higher-level constructs such as resource grouping, networking integration, and user-facing workflows. This separation allows physical and virtual resources to be managed under a consistent operational model without tightly coupling CloudStack to bare metal–specific logic.

How the Integration Works

The MAAS orchestrator is implemented using the Extensions Framework in CloudStack, which allows CloudStack to delegate resource lifecycle operations to external orchestrators in a controlled and decoupled way.

In this model, the MAAS integration is defined as an Extension of type Orchestrator, associated with a Cluster. Rather than embedding bare metal–specific logic into CloudStack’s core Java codebase, the integration runs as an external Python-based component.

The extension communicates with Canonical MAAS using its REST APIs and is responsible for executing lifecycle actions on physical servers, such as deploy, start, stop, reboot, and release. CloudStack remains responsible for higher-level orchestration concerns, including user workflows, resource grouping, and integration with networking and access control.

Once configured, this integration allows CloudStack to:

• Discover and manage physical servers registered in MAAS
• Trigger operating system deployment on bare metal servers
• Track Instance state and lifecycle events through the CloudStack UI and APIs
• Apply CloudStack networking constructs, such as Shared Networks and the Virtual Router where applicable

By externalising orchestration logic, the Extensions Framework keeps the CloudStack core clean while enabling support for infrastructure types that fall outside traditional hypervisor-based virtualisation.

Preparing the MAAS Environment

Before CloudStack can interact with MAAS, the MAAS service must be installed, configured, and reachable from the CloudStack Management Server. This includes network connectivity, API access, and proper authentication configuration.

CloudStack authenticates to MAAS using an API key. This key is generated in the MAAS UI under Admin > API Keys and is required when registering the MAAS Host in CloudStack.

Once generated, the API key can be validated using the MAAS CLI:

maas login admin http://<MAAS-ENDPOINT>:5240/MAAS <API_KEY>

maas admin machines read | jq ‘.[].system_id’

 

A successful response confirms that the API key is valid and that CloudStack can query the MAAS environment.

Because the MAAS orchestrator uses OAuth1 authentication, the CloudStack Management Server must have the required Python dependencies installed. Ensure the following libraries are available:

pip3 install requests requests_oauthlib

 

These libraries are required by the Python-based extension to authenticate and communicate with MAAS over its REST APIs.

At this stage, MAAS should already have physical machines enlisted and commissioned, with power management properly configured. CloudStack relies on MAAS to manage hardware state and availability, while CloudStack itself remains agnostic of the underlying bare metal details.

Integrating MAAS in CloudStack

With the MAAS environment installed, configured, and accessible from the CloudStack Management Server, the next step is to integrate it into CloudStack using the built-in MAAS extension.

Apache CloudStack includes a native MAAS extension, so no additional components need to be installed. The integration is performed by defining CloudStack objects that reference an existing MAAS environment and by mapping CloudStack templates to images managed by MAAS.

The built-in MAAS extension is visible directly in the CloudStack UI under the Extensions section, as shown below.

The integration process consists of creating a Cluster and a Host associated with the MAAS environment, followed by registering Templates that correspond to images available in MAAS.

When creating a Cluster, select the following options:

• Hypervisor: External
• Extension: MAAS

 

After the Cluster is created, add a Host corresponding to the MAAS server. This Host represents the MAAS endpoint that CloudStack will communicate with.

When adding the Host, provide the following parameters:

• endpoint: the MAAS API endpoint (for example, http://<maas-ip>:5240/MAAS/api/2.0)
• apikey: the MAAS API key generated in the MAAS UI

Templates registered in CloudStack correspond to images available in MAAS. When registering a Template, the extension details must include attributes that match the MAAS image metadata.

Typical extension attributes include:

os=ubuntu

distro_series=focal

architecture=amd64/ga-20.04

Deploying Bare Metal Instances

Once the integration is in place, deploying a Bare Metal Instance in CloudStack follows the same high-level workflow used for Virtual Machine Instances.

During Instance creation, Administrators select a Template backed by the MAAS extension. CloudStack then delegates the provisioning request to MAAS, which allocates a physical server from its available pool and installs the selected operating system.

After the deployment request is submitted, CloudStack tracks the Instance lifecycle while MAAS performs the bare metal provisioning process. This includes power control, PXE booting, operating system installation, and initial configuration.

The Instance status is updated in the CloudStack UI as MAAS reports progress back to CloudStack through the extension interface.

From the User’s perspective, Bare Metal Instances behave consistently with other CloudStack-managed resources. Lifecycle actions such as start, stop, reboot, and delete are available directly from the CloudStack UI and are translated into the appropriate MAAS operations behind the scenes.

This unified workflow allows Users to manage physical and virtual resources side by side, using the same tooling and operational model.

Networking and SSH Keypairs

Networking for MAAS-managed Bare Metal Instances has been validated using Shared Network configurations in Apache CloudStack, with Ubuntu-based images provisioned by Canonical MAAS.

When CloudStack’s Virtual Router is used as the DHCP provider, MAAS’s internal DHCP service must be disabled to avoid conflicts. In MAAS, this requires adjusting the subnet configuration as follows:

• Managed allocation: disabled
• Active discovery: enabled
• Server interfaces set to DHCP mode

This configuration ensures that CloudStack retains control over IP address allocation and network services, while MAAS focuses exclusively on bare metal provisioning and lifecycle management.

For SSH access, CloudStack keypairs can be reused with MAAS-provisioned Instances. To enable this, export the public key from CloudStack and import it into MAAS under Admin > SSH Keys. Once configured, this allows secure, key-based access to deployed physical servers using the same credentials managed by CloudStack.

This approach keeps networking and access control consistent across both virtual and Bare Metal Instances, reducing operational complexity and aligning bare metal provisioning with existing CloudStack workflows.

More details can be found at https://docs.cloudstack.apache.org/en/latest/adminguide/extensions.html#maas

Conclusion

The MAAS integration illustrates the intent and flexibility of Apache CloudStack’s Extensions Framework. By providing a structured way to delegate provisioning and lifecycle operations to external orchestrators, the framework allows CloudStack to manage resources that fall outside its traditional hypervisor-based model.

Through the integration with Canonical MAAS, CloudStack can now orchestrate bare metal infrastructure alongside Virtual Machine Instances using consistent workflows, APIs, and access control mechanisms. Physical servers are treated as first-class resources, while the complexity of hardware provisioning and power management remains encapsulated within MAAS.

Equally important, this integration demonstrates a broader architectural direction. External orchestrators can be integrated without increasing complexity in CloudStack’s core codebase, enabling operators to adapt the platform to diverse infrastructure needs, from bare metal and edge deployments to specialised environments.

Together, the Extensions Framework and the MAAS integration extend CloudStack’s scope beyond virtualised workloads, supporting hybrid environments where physical and virtual resources coexist under a single, open-source cloud management platform.