diff --git a/source/_static/images/CloudStack-shared-network.png b/source/_static/images/CloudStack-shared-network.png new file mode 100644 index 0000000000..cb87b6a59b 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 0000000000..51169322cd 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 0000000000..11d2934f33 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 0000000000..5451cfe282 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 0000000000..7711104991 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 0000000000..a58af418e5 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 0000000000..14ceb50fc2 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 0000000000..28a3b2715f 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 0000000000..c1f79504bb 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 0000000000..78d3530f40 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 0000000000..9fba0e8525 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 0000000000..07d7345aee 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 0000000000..3bcf805c06 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 664cefa854..8970333a19 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 071d6c688a..a322cacbae 100644 --- a/source/adminguide/extensions.rst +++ b/source/adminguide/extensions.rst @@ -79,7 +79,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 758941fce6..9f56f5a7a3 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 `_ over HTTPS." Before using the Proxmox Extension, ensure that the Proxmox Datacenter is configured correctly and accessible to CloudStack. @@ -267,8 +267,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 +^^^^^^^^ + +The MaaS CloudStack Extension is written in python script and communicates with `Canonical MaaS `_ using the `MaaS APIs `_. + +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://:5240/MAAS + + # 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://: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| + -.. _Proxmox VE API: https://pve.proxmox.com/pve-docs/api-viewer/index.html + After these steps, any baremetal node deployed via the MAAS Extension can be accessed using the **private key** from CloudStack. .. Images @@ -285,3 +458,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