This is an automated email from the ASF dual-hosted git repository.
rohit pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new be2b8bd3 Added documentation for MaaS Extension (#561)
be2b8bd3 is described below
commit be2b8bd3ac57fbe611c19bfa44b6957ae3540f01
Author: Harikrishna <[email protected]>
AuthorDate: Fri Oct 10 09:46:24 2025 +0530
Added documentation for MaaS Extension (#561)
* Added documentation for MaaS Extension
* Some corrections
* doc changes
* template changes
* few edits
* Shorten the text
* Doc and image changes
* more details
* Update source/adminguide/extensions/inbuilt_extensions.rst
* Update source/adminguide/extensions/inbuilt_extensions.rst
---------
Co-authored-by: Rohit Yadav <[email protected]>
---
.../_static/images/CloudStack-shared-network.png | Bin 0 -> 66493 bytes
source/_static/images/MaaS-add-cluster.png | Bin 0 -> 46587 bytes
source/_static/images/MaaS-add-host.png | Bin 0 -> 53830 bytes
source/_static/images/MaaS-add-reserve-iprange.png | Bin 0 -> 49483 bytes
source/_static/images/MaaS-add-sshkeypair.png | Bin 0 -> 130139 bytes
source/_static/images/MaaS-add-subnet-1.png | Bin 0 -> 45202 bytes
source/_static/images/MaaS-add-subnet-2.png | Bin 0 -> 118204 bytes
source/_static/images/MaaS-add-template.png | Bin 0 -> 80336 bytes
source/_static/images/MaaS-add-token.png | Bin 0 -> 84418 bytes
source/_static/images/MaaS-deploy-instance.png | Bin 0 -> 139240 bytes
source/_static/images/MaaS-disable-dhcp.png | Bin 0 -> 62098 bytes
.../_static/images/MaaS-enable-dhcp-on-servers.png | Bin 0 -> 95028 bytes
.../_static/images/MaaS-subnet-configuration.png | Bin 0 -> 66103 bytes
source/_static/images/built-in-extensions.png | Bin 134959 -> 53481 bytes
source/adminguide/extensions.rst | 2 +-
.../adminguide/extensions/inbuilt_extensions.rst | 198 ++++++++++++++++++++-
16 files changed, 193 insertions(+), 7 deletions(-)
diff --git a/source/_static/images/CloudStack-shared-network.png
b/source/_static/images/CloudStack-shared-network.png
new file mode 100644
index 00000000..cb87b6a5
Binary files /dev/null and
b/source/_static/images/CloudStack-shared-network.png differ
diff --git a/source/_static/images/MaaS-add-cluster.png
b/source/_static/images/MaaS-add-cluster.png
new file mode 100644
index 00000000..51169322
Binary files /dev/null and b/source/_static/images/MaaS-add-cluster.png differ
diff --git a/source/_static/images/MaaS-add-host.png
b/source/_static/images/MaaS-add-host.png
new file mode 100644
index 00000000..11d2934f
Binary files /dev/null and b/source/_static/images/MaaS-add-host.png differ
diff --git a/source/_static/images/MaaS-add-reserve-iprange.png
b/source/_static/images/MaaS-add-reserve-iprange.png
new file mode 100644
index 00000000..5451cfe2
Binary files /dev/null and b/source/_static/images/MaaS-add-reserve-iprange.png
differ
diff --git a/source/_static/images/MaaS-add-sshkeypair.png
b/source/_static/images/MaaS-add-sshkeypair.png
new file mode 100644
index 00000000..77111049
Binary files /dev/null and b/source/_static/images/MaaS-add-sshkeypair.png
differ
diff --git a/source/_static/images/MaaS-add-subnet-1.png
b/source/_static/images/MaaS-add-subnet-1.png
new file mode 100644
index 00000000..a58af418
Binary files /dev/null and b/source/_static/images/MaaS-add-subnet-1.png differ
diff --git a/source/_static/images/MaaS-add-subnet-2.png
b/source/_static/images/MaaS-add-subnet-2.png
new file mode 100644
index 00000000..14ceb50f
Binary files /dev/null and b/source/_static/images/MaaS-add-subnet-2.png differ
diff --git a/source/_static/images/MaaS-add-template.png
b/source/_static/images/MaaS-add-template.png
new file mode 100644
index 00000000..28a3b271
Binary files /dev/null and b/source/_static/images/MaaS-add-template.png differ
diff --git a/source/_static/images/MaaS-add-token.png
b/source/_static/images/MaaS-add-token.png
new file mode 100644
index 00000000..c1f79504
Binary files /dev/null and b/source/_static/images/MaaS-add-token.png differ
diff --git a/source/_static/images/MaaS-deploy-instance.png
b/source/_static/images/MaaS-deploy-instance.png
new file mode 100644
index 00000000..78d3530f
Binary files /dev/null and b/source/_static/images/MaaS-deploy-instance.png
differ
diff --git a/source/_static/images/MaaS-disable-dhcp.png
b/source/_static/images/MaaS-disable-dhcp.png
new file mode 100644
index 00000000..9fba0e85
Binary files /dev/null and b/source/_static/images/MaaS-disable-dhcp.png differ
diff --git a/source/_static/images/MaaS-enable-dhcp-on-servers.png
b/source/_static/images/MaaS-enable-dhcp-on-servers.png
new file mode 100644
index 00000000..07d7345a
Binary files /dev/null and
b/source/_static/images/MaaS-enable-dhcp-on-servers.png differ
diff --git a/source/_static/images/MaaS-subnet-configuration.png
b/source/_static/images/MaaS-subnet-configuration.png
new file mode 100644
index 00000000..3bcf805c
Binary files /dev/null and
b/source/_static/images/MaaS-subnet-configuration.png differ
diff --git a/source/_static/images/built-in-extensions.png
b/source/_static/images/built-in-extensions.png
index 664cefa8..8970333a 100644
Binary files a/source/_static/images/built-in-extensions.png and
b/source/_static/images/built-in-extensions.png differ
diff --git a/source/adminguide/extensions.rst b/source/adminguide/extensions.rst
index 10fe360e..2c6b7308 100644
--- a/source/adminguide/extensions.rst
+++ b/source/adminguide/extensions.rst
@@ -81,7 +81,7 @@ An Orchestrator extension enables CloudStack to delegate VM
orchestration to an
|extension.png|
-CloudStack provides in-built Orchestrator Extensions for Proxmox and Hyper-V
which work with Proxmox and Hyper-V environments out of the box.
+CloudStack provides built-in Orchestrator Extensions for Proxmox, Hyper-V, and
MaaS, which work with their respective environments out of the box.
.. note::
- When a CloudStack host linked to an orchestrator extension is placed into
Maintenance mode, all running instances on the host will be stopped.
diff --git a/source/adminguide/extensions/inbuilt_extensions.rst
b/source/adminguide/extensions/inbuilt_extensions.rst
index 34df6507..d0641e29 100644
--- a/source/adminguide/extensions/inbuilt_extensions.rst
+++ b/source/adminguide/extensions/inbuilt_extensions.rst
@@ -16,10 +16,10 @@
In-built Orchestrator Extensions
================================
-CloudStack provides in-built Orchestrator Extensions for Proxmox and Hyper-V.
These extensions work with Proxmox and Hyper-V environments out of the box, and
can also serve as reference implementations for anyone looking to develop new
custom extensions.
-The Extension files are located at
`/usr/share/cloudstack-management/extensions/Proxmox` and
`/usr/share/cloudstack-management/extensions/HyperV` respectively.
-The Proxmox Extension is written in shell script, while the Hyper-V Extension
is written in python.
-Both of these Extensions support some custom actions in addition to the
standard VM actions like deploy, start, stop, reboot, status and delete.
+CloudStack provides in-built Orchestrator Extensions for Proxmox, Hyper-V and
MaaS. These extensions work with Proxmox, Hyper-V and MaaS environments out of
the box, and can also serve as reference implementations for anyone looking to
develop new custom extensions.
+The Extension files are located in
`/usr/share/cloudstack-management/extensions/`, under the subdirectories
`Proxmox`, `HyperV`, and `MaaS`.
+The Proxmox Extension is written in shell script, while the Hyper-V and MaaS
Extensions are written in python.
+Proxmox and Hyper-V Extensions support some custom actions in addition to the
standard VM actions like deploy, start, stop, reboot, status and delete.
After installing or upgrading CloudStack, in-built Extensions will show up in
the Extensions section in UI.
|built-in-extensions.png|
@@ -29,7 +29,7 @@ After installing or upgrading CloudStack, in-built Extensions
will show up in th
Proxmox
^^^^^^^^
-The Proxmox CloudStack Extension is written in shell script and communicates
with the Proxmox Cluster using the `Proxmox VE API`_ over HTTPS.
+The Proxmox CloudStack Extension is written in shell script and communicates
with the Proxmox Cluster using the `Proxmox VE API
<https://pve.proxmox.com/wiki/Proxmox_VE_API>`_ over HTTPS."
Before using the Proxmox Extension, ensure that the Proxmox Datacenter is
configured correctly and accessible to CloudStack.
@@ -278,8 +278,181 @@ The VR responds with the correct IP address as configured
in CloudStack. Once th
Users can then manage the Hyper-V VM like any other CloudStack guest Instance.
Users can apply Egress Policies,
Firewall Rules, Port Forwarding, and other networking features seamlessly
through the CloudStack UI or API.
+MaaS
+^^^^
-.. _Proxmox VE API: https://pve.proxmox.com/pve-docs/api-viewer/index.html
+The MaaS Extension for CloudStack is written in Python and communicates with
`Canonical MaaS <https://canonical.com/maas>`_ using the `MaaS APIs
<https://canonical.com/maas/docs/api>`_.
+
+Before using the MaaS Extension, ensure that the Canonical MaaS Service is
configured correctly with servers added into it and accessible to CloudStack.
+
+Get the API key from MaaS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If not already set up, create a new API Key in the MaaS UI by navigating to
left column under `admin > API keys`.
+
+Existing `MAAS consumer` token can be used or a new API key can be generated
by clicking the `Generate MAAS API Key` button
+
+ |MaaS-add-token.png|
+
+Note down the **key** value.
+
+You can verify the MAAS API key and connectivity from the CloudStack
Management Server by using the MAAS CLI as shown below (replace the example
values with your own):
+
+.. code-block:: bash
+
+ maas login admin http://<MAAS-ENDPOINT>:5240/MAAS <API_KEY>
+
+ # Example:
+ maas login admin http://10.0.80.47:5240/MAAS
QqeFTc4fvz9qQyPzGy:UUGKTDf6VwPVDnhXUp:wtAZk6rKeHrFLyDQD9sWcASPkZVSMu6a
+
+ # Verify MAAS connectivity and list machines
+ maas admin machines read | jq '.[].system_id'
+
+If the connection is successful, the command will list all registered machine
system IDs from MAAS.
+
+Install required Python libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The MAAS Orchestrator Extension uses OAuth1 for API authentication.
+
+Ensure the required Python libraries are installed on the CloudStack
Management Server before using this extension.
+The following command is provided as an example, package installation steps
may vary depending on the host operating system:
+
+.. code-block:: bash
+
+ pip3 install requests requests_oauthlib
+
+Adding MaaS to CloudStack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To set up the MaaS Extension, follow these steps in CloudStack:
+
+#. **Use Default Extension**
+
+ A default MaaS Extension is already available and enabled under
`Extensions` tab.
+
+#. **Create Cluster**
+
+ Create a Cluster with Hypervisor type `External` and Extension type `MaaS`.
+
+ |MaaS-add-cluster.png|
+
+#. **Add Host**
+
+ Add a Host to the newly created Cluster with the following details:
+
+ To access MaaS environment, the `endpoint`, `apikey` need to be set in the
Host.
+
+ * **endpoint**: IP address of the MaaS server. The API used for operations
in the script will look like `http://<endpoint>:5240/MAAS/api/2.0`.
+ * **apikey**: API key for MaaS
+
+ |MaaS-add-host.png|
+
+
+#. **Create Template**
+
+ A Template in CloudStack maps to an image available in MaaS that can be
deployed on a baremetal server.
+ Provide a dummy `url` and template name. Select `External` as the
hypervisor and `MaaS` as the extension.
+ Under `External Details`, specify the following parameters:
+
+ * **os**: Operating system name (e.g., `ubuntu`)
+ * **distro_series**: Ubuntu codename (e.g., `focal`, `jammy`)
+ * **architecture**: Image architecture name as listed in MaaS (e.g.,
`amd64/ga-20.04`, `amd64/hwe-22.04`, `amd64/generic`)
+
+ MAAS uses only distro_series to identify the operating system for
Ubuntu-based images (for example, focal, jammy).
+
+ Example configurations:
+
+ .. code-block:: text
+
+ # Ubuntu 20.04 (Focal)
+ os=ubuntu
+ distro_series=focal
+ architecture=amd64/ga-20.04
+
+ |MaaS-add-template.png|
+
+#. **Deploy Instance**
+
+ Deploy an Instance using the Template created above. The Instance will be
provisioned on a randomly selected MaaS machine.
+ **maas_system_id** value can be provided in the external details to deploy
the instance on specific server.
+
+ |MaaS-deploy-instance.png|
+
+#. **Lifecycle Operations**
+
+ Operations **Start**, **Stop**, **Reboot**, and **Delete** can be performed
on the Instance from CloudStack.
+
+Configuring Networking and additional details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The MaaS scenarios have been tested and verified only with a Shared Network
setup in CloudStack and with ubuntu based images, using the MAAS Orchestrator
Extension.
+Please find some additional notes with respect to the networking and access
related configuration as below,
+
+#. **Configuring TFTP to point to MAAS**
+
+ Ensure that the TFTP or PXE boot configuration (for example, in pfSense or
your network’s DHCP server) is set to point to the MAAS server as the TFTP
source.
+ This ensures that VMs retrieve boot images directly from MAAS during PXE
boot.
+
+#. **Using CloudStack Virtual Router (VR) as an External DHCP Server**
+
+ If the end user wants the **CloudStack Virtual Router (VR)** to act as the
external DHCP server for instances provisioned through MAAS, the following
configuration steps must be performed.
+
+ **In CloudStack**
+
+ a. Navigate to **Networks → Add Shared Network**.
+ b. Create a Shared Network using the **DefaultSharedNetworkOffering**, and
define an appropriate **Guest IP range**.
+
+ |CloudStack-shared-network.png|
+
+ **In MAAS**
+
+ a. Navigate to **Networking → Subnets → Add Subnet** and create a subnet
corresponding to the same IP range used in CloudStack.
+
+ |MaaS-add-subnet-1.png|
+ |MaaS-add-subnet-2.png|
+
+ b. Once the subnet is added:
+ - Ensure **Managed allocation** is **disabled**.
+ - Ensure **Active discovery** is **enabled**.
+
+ |MaaS-subnet-configuration.png|
+
+ c. Add a **Reserved IP range** that matches the CloudStack Guest range
(optional, for clarity).
+
+ |MaaS-add-reserve-iprange.png|
+
+ d. Disable the DHCP service in MAAS:
+ - Navigate to **Subnets → VLAN → Edit VLAN**.
+ - Ensure the **DHCP service** is **disabled**.
+
+ |MaaS-disable-dhcp.png|
+
+ e. For all the servers in MAAS, navigate to each server in the Ready state,
go to Network → Server Interface → Edit Physical, and set the IP mode to DHCP.
+
+ |MaaS-enable-dhcp-on-servers.png|
+
+ This configuration allows the CloudStack Virtual Router (VR) to provide IP
address allocation and DHCP services for the baremetal instances managed
through MAAS.
+
+#. **Using CloudStack-Generated SSH Keys for Baremetal Access**
+
+ If the user wants to use the **SSH key pair generated in CloudStack** to
log into the baremetal server provisioned by MAAS, perform the following steps.
+
+ **In CloudStack**
+
+ a. Navigate to **Compute → SSH Keypairs → Create SSH Keypair**.
+ b. Save the generated **private key** for later use (CloudStack stores only
the public key).
+
+ **In MAAS**
+
+ a. Navigate to **Admin → SSH Keys → Import**.
+ b. Paste the **public key** from the CloudStack-generated SSH key pair.
+ c. Save the changes.
+
+ |MaaS-add-sshkeypair.png|
+
+
+ After these steps, any baremetal node deployed via the MAAS Extension can
be accessed using the **private key** from CloudStack.
.. Images
@@ -296,3 +469,16 @@ Firewall Rules, Port Forwarding, and other networking
features seamlessly throug
.. |hyperv-add-host.png| image:: /_static/images/hyperv-add-host.png
.. |hyperv-add-template.png| image:: /_static/images/hyperv-add-template.png
.. |hyperv-add-iso.png| image:: /_static/images/hyperv-add-iso.png
+.. |MaaS-add-token.png| image:: /_static/images/MaaS-add-token.png
+.. |MaaS-add-cluster.png| image:: /_static/images/MaaS-add-cluster.png
+.. |MaaS-add-host.png| image:: /_static/images/MaaS-add-host.png
+.. |MaaS-add-template.png| image:: /_static/images/MaaS-add-template.png
+.. |MaaS-deploy-instance.png| image:: /_static/images/MaaS-deploy-instance.png
+.. |CloudStack-shared-network.png| image::
/_static/images/CloudStack-shared-network.png
+.. |MaaS-add-subnet-1.png| image:: /_static/images/MaaS-add-subnet-1.png
+.. |MaaS-add-subnet-2.png| image:: /_static/images/MaaS-add-subnet-2.png
+.. |MaaS-subnet-configuration.png| image::
/_static/images/MaaS-subnet-configuration.png
+.. |MaaS-add-reserve-iprange.png| image::
/_static/images/MaaS-add-reserve-iprange.png
+.. |MaaS-disable-dhcp.png| image:: /_static/images/MaaS-disable-dhcp.png
+.. |MaaS-add-sshkeypair.png| image:: /_static/images/MaaS-add-sshkeypair.png
+.. |MaaS-enable-dhcp-on-servers.png| image::
/_static/images/MaaS-enable-dhcp-on-servers.png
\ No newline at end of file
