Added documentation for MaaS Extension

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 in-built Orchestrator Extensions for Proxmox, Hyper-V, MaaS which work with Proxmox, Hyper-V and MaaS 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.

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 at `/usr/share/cloudstack-management/extensions/Proxmox`, `/usr/share/cloudstack-management/extensions/HyperV` and `/usr/share/cloudstack-management/extensions/MaaS` respectively.
+The Proxmox Extension is written in shell script, while the Hyper-V and MaaS Extensions are written in python.
+All of these 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|
@@ -267,8 +267,70 @@ 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 the 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 used or a new API key can be generated by clicking `Generate MAAS API Key` button
+
+   |MaaS-add-token.png|
+
+Note down the **key** value.
+
+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 can map to either a `Template` or an `ISO` in MaaS.
+   Provide a dummy `url` and template name. Select `External` as the hypervisor and `MaaS` as the extension. Under `External Details`, specify:
 
-.. _Proxmox VE API: https://pve.proxmox.com/pve-docs/api-viewer/index.html
+   * **distro_series**: The name of the operating system series available in MaaS to install on the machine. If not specified, script defaults to `ubuntu`
+
+   |MaaS-add-template.png|
+
+#. **Deploy Instance**
+
+   Deploy an Instance using the Template created above. Optionally, provide the detail `vm_name` to specify the name of the VM in MaaS.
+   Otherwise, the CloudStack Instance's internal name is used. The Instance will be provisioned on a randomly selected MaaS machine.
+
+   |MaaS-deploy-instance.png|
+
+#. **Lifecycle Operations**
+
+   Operations **Start**, **Stop**, **Reboot**, and **Delete** can be performed on the Instance from CloudStack.
 
 .. Images
 
@@ -285,3 +347,8 @@ 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