This is an automated email from the ASF dual-hosted git repository.
sureshanaparti 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 9cd0be3 feature: extensions (#523)
9cd0be3 is described below
commit 9cd0be30dbcb10316143d3a6f37e98e8f6f46ac2
Author: Abhishek Kumar <abhishek.mr...@gmail.com>
AuthorDate: Mon Jul 28 11:03:48 2025 +0530
feature: extensions (#523)
* feature: extensions
For https://github.com/apache/cloudstack/pull/9752
Signed-off-by: Abhishek Kumar <abhishek.mr...@gmail.com>
Co-authored-by: Abhisar Sinha <63767682+abh1...@users.noreply.github.com>
---
source/_static/images/add-custom-action.png | Bin 0 -> 92075 bytes
source/_static/images/built-in-extensions.png | Bin 0 -> 121934 bytes
source/_static/images/create-extension.png | Bin 0 -> 56904 bytes
source/_static/images/extension.png | Bin 0 -> 68190 bytes
source/_static/images/extensions.png | Bin 0 -> 118402 bytes
source/_static/images/hyperv-add-cluster.png | Bin 0 -> 119648 bytes
source/_static/images/hyperv-add-host.png | Bin 0 -> 219842 bytes
source/_static/images/hyperv-add-iso.png | Bin 0 -> 126667 bytes
source/_static/images/hyperv-add-template.png | Bin 0 -> 200770 bytes
source/_static/images/proxmox-add-cluster.png | Bin 0 -> 122951 bytes
source/_static/images/proxmox-add-host.png | Bin 0 -> 209573 bytes
source/_static/images/proxmox-add-iso.png | Bin 0 -> 93078 bytes
source/_static/images/proxmox-add-template.png | Bin 0 -> 187080 bytes
source/_static/images/proxmox-add-token.png | Bin 0 -> 53117 bytes
.../images/proxmox-api-token-permission.png | Bin 0 -> 61829 bytes
source/_static/images/proxmox-deploy-instance.png | Bin 0 -> 131046 bytes
.../_static/images/run-custom-action-instance.png | Bin 0 -> 61589 bytes
source/_static/images/run-custom-action.png | Bin 0 -> 25941 bytes
source/adminguide/extensions.rst | 104 +++++++++
.../adminguide/extensions/builtin_extensions.rst | 240 +++++++++++++++++++++
source/adminguide/extensions/custom_actions.rst | 62 ++++++
source/adminguide/extensions/developer.rst | 186 ++++++++++++++++
source/adminguide/extensions/troubleshooting.rst | 70 ++++++
source/adminguide/index.rst | 9 +
24 files changed, 671 insertions(+)
diff --git a/source/_static/images/add-custom-action.png
b/source/_static/images/add-custom-action.png
new file mode 100644
index 0000000..4d8362e
Binary files /dev/null and b/source/_static/images/add-custom-action.png differ
diff --git a/source/_static/images/built-in-extensions.png
b/source/_static/images/built-in-extensions.png
new file mode 100644
index 0000000..960c394
Binary files /dev/null and b/source/_static/images/built-in-extensions.png
differ
diff --git a/source/_static/images/create-extension.png
b/source/_static/images/create-extension.png
new file mode 100644
index 0000000..166d32a
Binary files /dev/null and b/source/_static/images/create-extension.png differ
diff --git a/source/_static/images/extension.png
b/source/_static/images/extension.png
new file mode 100644
index 0000000..d72c2c9
Binary files /dev/null and b/source/_static/images/extension.png differ
diff --git a/source/_static/images/extensions.png
b/source/_static/images/extensions.png
new file mode 100644
index 0000000..36ada99
Binary files /dev/null and b/source/_static/images/extensions.png differ
diff --git a/source/_static/images/hyperv-add-cluster.png
b/source/_static/images/hyperv-add-cluster.png
new file mode 100644
index 0000000..c1840cd
Binary files /dev/null and b/source/_static/images/hyperv-add-cluster.png differ
diff --git a/source/_static/images/hyperv-add-host.png
b/source/_static/images/hyperv-add-host.png
new file mode 100644
index 0000000..4fb1ca7
Binary files /dev/null and b/source/_static/images/hyperv-add-host.png differ
diff --git a/source/_static/images/hyperv-add-iso.png
b/source/_static/images/hyperv-add-iso.png
new file mode 100644
index 0000000..1f793b1
Binary files /dev/null and b/source/_static/images/hyperv-add-iso.png differ
diff --git a/source/_static/images/hyperv-add-template.png
b/source/_static/images/hyperv-add-template.png
new file mode 100644
index 0000000..8cd7360
Binary files /dev/null and b/source/_static/images/hyperv-add-template.png
differ
diff --git a/source/_static/images/proxmox-add-cluster.png
b/source/_static/images/proxmox-add-cluster.png
new file mode 100644
index 0000000..53e91bf
Binary files /dev/null and b/source/_static/images/proxmox-add-cluster.png
differ
diff --git a/source/_static/images/proxmox-add-host.png
b/source/_static/images/proxmox-add-host.png
new file mode 100644
index 0000000..f251ab3
Binary files /dev/null and b/source/_static/images/proxmox-add-host.png differ
diff --git a/source/_static/images/proxmox-add-iso.png
b/source/_static/images/proxmox-add-iso.png
new file mode 100644
index 0000000..219f89c
Binary files /dev/null and b/source/_static/images/proxmox-add-iso.png differ
diff --git a/source/_static/images/proxmox-add-template.png
b/source/_static/images/proxmox-add-template.png
new file mode 100644
index 0000000..dc14d1e
Binary files /dev/null and b/source/_static/images/proxmox-add-template.png
differ
diff --git a/source/_static/images/proxmox-add-token.png
b/source/_static/images/proxmox-add-token.png
new file mode 100644
index 0000000..313394c
Binary files /dev/null and b/source/_static/images/proxmox-add-token.png differ
diff --git a/source/_static/images/proxmox-api-token-permission.png
b/source/_static/images/proxmox-api-token-permission.png
new file mode 100644
index 0000000..39091e3
Binary files /dev/null and
b/source/_static/images/proxmox-api-token-permission.png differ
diff --git a/source/_static/images/proxmox-deploy-instance.png
b/source/_static/images/proxmox-deploy-instance.png
new file mode 100644
index 0000000..78a067b
Binary files /dev/null and b/source/_static/images/proxmox-deploy-instance.png
differ
diff --git a/source/_static/images/run-custom-action-instance.png
b/source/_static/images/run-custom-action-instance.png
new file mode 100644
index 0000000..9da4e9e
Binary files /dev/null and
b/source/_static/images/run-custom-action-instance.png differ
diff --git a/source/_static/images/run-custom-action.png
b/source/_static/images/run-custom-action.png
new file mode 100644
index 0000000..ae7a10c
Binary files /dev/null and b/source/_static/images/run-custom-action.png differ
diff --git a/source/adminguide/extensions.rst b/source/adminguide/extensions.rst
new file mode 100644
index 0000000..3f57324
--- /dev/null
+++ b/source/adminguide/extensions.rst
@@ -0,0 +1,104 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+Extensions
+==========
+
+Extensions are a new mechanism introduced in Apache CloudStack to allow
administrators to extend the platform's functionality by integrating external
systems or custom workflows. Currently, CloudStack supports a single extension
type called Orchestrator.
+
+In the UI, extensions can be managed under *Extensions* menu.
+
+ |extensions.png|
+
+Overview
+^^^^^^^^
+
+An extension in CloudStack is defined as an external binary (written in any
programming language) that implements specific actions CloudStack can invoke.
This allows operators to manage resource lifecycle operations outside
CloudStack, such as provisioning VMs in third-party systems or triggering
external automation pipelines.
+
+Extensions are managed through the API and UI, with support for configuration,
resource mappings, and action execution.
+
+ |create-extension.png|
+
+Configuration
+^^^^^^^^^^^^^
+
+Administrators can define and manage the following components of an extension:
+
+ - Path: A path to a file or script that will be executed during extension
operations.
+
+ - Configuration Details: Key-value properties used by the extension at
runtime.
+
+ - Resource Mappings: Association between extensions and CloudStack
resources such as clusters, etc.
+
+Path and Availabilty
+^^^^^^^^^^^^^^^^^^^^
+
+The path for an extension can point to any binary or executable script. If no
explicit path is provided, CloudStack uses a default base Bash script. The
state of the path is validated across all management servers. In the UI, the
Availabilty is displayed as Not Ready if the file is missing, inaccessible, or
differs across management servers.
+
+All extension files are stored under a directory named after the extension
within `/usr/share/cloudstack-management/extensions`.
+
+Payload
+^^^^^^^
+
+CloudStack sends structured JSON payloads to the extension binary during each
operation. These payloads are written to .json files stored under
`/var/lib/cloudstack/management/extensions`. The extension binary is expected
to read the file and return an appropriate result. CloudStack automatically
attempts to clean up payload files older than one day.
+
+Orchestrator Extension
+^^^^^^^^^^^^^^^^^^^^^^
+
+An Orchestrator extension enables CloudStack to delegate VM orchestration to
an external system. Key features include:
+
+ - Cluster Mapping: Orchestrator extensions can be associated with one or
more CloudStack clusters.
+
+ - Hosts: Multiple hosts can be added to such clusters, ideally pointing to
different physical or external hosts.
+
+ - Instance Lifecycle Support: Extensions can handle basic VM actions like
prepare, deploy, start, stop, reboot, status and delete.
+
+ - Configuration Details: Key-value configuration details can be specified
at different levels - extension, cluster mapping, host, template, service
offering, instance.
+
+ - Custom Actions: Admins can define custom actions beyond the standard VM
operations.
+
+ - Instance Preparation: Orchestrator extensions can optionally perform a
preparation step during instance deployment. This step is executed before the
instance is started on the external system. It allows the extension to update
certain instance details in CloudStack. CloudStack sends a structured JSON
containing the instance configuration, and the extension can respond with the
values it wishes to modify. Currently, only a limited set of fields can be
updated: the instance’s VNC pass [...]
+
+ - Networking: If networking is setup properly on the external system (See
:ref:`built-in extensions networking <proxmox-networking>` for more details.),
the Virtual Router in CloudStack can connect to the external VMs and provide
DHCP, DNS, and routing services.
+
+ **Note**: User data and ssh-key injection from within CloudStack is not
supported for the external VMs in this release. The External systems should
handle user-data and ssh-key injections natively using other mechanisms.
+
+ |extension.png|
+
+
+CloudStack provides sample built-in orchestrator extensions for demonstration
and testing purposes.
+
+.. note::
+ - When a CloudStack host linked to an orchestrator extension is placed into
Maintenance mode, all running instances on the host will be stopped.
+
+ - For hosts linked to extensions, CloudStack will report zero for CPU and
memory capacity, and host metrics will reflect the same. During instance
deployment, capacity checks are the responsibility of the extension executable;
CloudStack will not perform any capacity calculations.
+
+ - Some of the features that rely on interaction with VMs, such as VM
snapshots, live migration, VM scaling, VM autoscaling groups, VNF appliance,
Kubernetes clusters, etc are currently not supported for instances managed by
orchestrator extensions.
+
+.. include:: extensions/custom_actions.rst
+
+.. include:: extensions/builtin_extensions.rst
+
+.. include:: extensions/troubleshooting.rst
+
+.. include:: extensions/developer.rst
+
+.. Images
+
+
+.. |extensions.png| image:: /_static/images/extensions.png
+.. |create-extension.png| image:: /_static/images/create-extension.png
+.. |extension.png| image:: /_static/images/extension.png
diff --git a/source/adminguide/extensions/builtin_extensions.rst
b/source/adminguide/extensions/builtin_extensions.rst
new file mode 100644
index 0000000..17c1731
--- /dev/null
+++ b/source/adminguide/extensions/builtin_extensions.rst
@@ -0,0 +1,240 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Built-in Orchestator Extensions
+===============================
+
+CloudStack provides sample built-in orchestrator extensions for Proxmox and
Hyper-V. These extensions are intended for demonstration and testing purposes.
+The extension files are located at
`/usr/share/cloudstack-management/extensions/Promox` 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.
+After installing or upgrading Cloudstack, these extensions will show up as
disabled on the Extensions page in the UI.
+
+ |built-in-extensions.png|
+
+**Note**: These extension may undergo changes with different CloudStack
releases and backwards compatibility is not guaranteed.
+
+Proxmox
+^^^^^^^^
+
+The Proxmox Cloudstack extension is written in shell script and communicates
with a 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.
+
+Get the Api Token-Secret from Proxmox
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If not already set up, create a new API Token in the Proxmox UI by navigating
to `Datacenter > Permissions > API Tokens`.
+Uncheck the `Privilege Separation` checkbox in the `Add: Token` dialog or give
permission to the API Token
+by navigating to `Datacenter > Permissions > Add > API Tokens Permission` and
setting Role = `PVEAdmin` and Path = `/vms`.
+Note down the **user**, **token**, and **secret**.
+
+ |proxmox-add-token.png|
+ |proxmox-api-token-permission.png|
+
+To check whether the **token** and **secret** are working fine, you can check
the following from the CloudStack Management Server:
+
+.. code-block:: bash
+
+ export PVE_TOKEN='root@pam!<PROXMOX_TOKEN>=<PROXMOX_SECRET>'
+
+ curl -s -k -H "Authorization: PVEAPIToken=$PVE_TOKEN"
https://<PROXMOX_URL>:8006/api2/json/version | jq
+
+It should return a JSON response similar to this:
+
+.. code-block:: json
+
+ {
+ "data": {
+ "repoid": "ec58e45e1bcdf2ac",
+ "version": "8.4.0",
+ "release": "8.4"
+ }
+ }
+
+Adding Proxmox to CloudStack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To set up the Proxmox extension, follow these steps in CloudStack:
+
+#. **Enable extension.** Enable the extension by clicking the `Enable` button
on the `Extensions` page in the UI.
+#. **Create Cluster**. Create a Cluster with hypervisor type `External` and
extension type `Proxmox`.
+
+ |proxmox-add-cluster.png|
+
+#. **Add Host.** Add a host to the newly created cluster with the following
details:
+
+ If the Proxmox nodes use a shared API endpoint or credentials, the `url`,
`user`, `token`, and `secret` can be set in the Extension's `Configuration
Details` instead of per host. However, `node` and `network_bridge` must still
be specified individually for each host.
+
+ |proxmox-add-host.png|
+
+ **Note**: If the TLS certificate cannot be verified when cloudstack
connects to the Proxmox node, add the detail **verify_tls_certificate** and set
it to **false** to skip certificate verification.
+
+#. **Create Template.** A Template in CloudStack can map to either a
`Template` or an `ISO` in Proxmox.
+ Provide a dummy `url` and template name. Select `External` as the
hypervisor and `Proxmox` as the extension. Under `External Details`, specify:
+
+ * **template_type**: `template` or `iso`
+ * **template_id**: ID of the template in Proxmox (if `template_type` is
`template`)
+
+ |proxmox-add-template.png|
+
+ * **iso_path**: full path to the ISO in Proxmox (if `template_type` is
`iso`)
+ |proxmox-add-iso.png|
+
+ Note: Templates and ISOs should be stored on shared storage when using
multiple Proxmox nodes. Or copy the template/iso to each host's local storage
at the same location.
+
+#. **Deploy Instance.** Deploy an instance using the template created above.
Optionally, provide the detail `vm_name` to specify the name of the VM in
Proxmox.
+ Otherwise, the CloudStack instance's internal name is used. The VM Id in
Proxmox is mapped to the CloudStack instance and stored as a detail in
CloudStack DB.
+ The instance will be provisioned on a randomly selected Proxmox host. The
VM will be configured with the MAC address and VLAN ID as defined in CloudStack.
+
+ |proxmox-deploy-instance.png|
+
+#. **Lifecycle operations.** Operations **Start**, **Stop**, **Reboot**, and
**Delete** can be performed on the instance from CloudStack.
+
+#. **Custom actions.** Custom actions **Create Snapshot**, **Restore
Snapshot**, and **Delete Snapshot** are also supported for instances.
+
+.. _proxmox-networking:
+Configuring Networking
+~~~~~~~~~~~~~~~~~~~~~~
+
+Proxmox nodes and CloudStack hypervisor hosts must be connected via a VLAN
trunked network. On each Proxmox node,
+a bridge interface should be created and connected to the network interface
that carries the VLAN-tagged traffic.
+This bridge must be specified under Configuration Details (`network_bridge`)
when registering the Proxmox node as a host in CloudStack.
+
+When a VM is deployed, CloudStack includes the assigned MAC address and VLAN
ID in the extension payload.
+The VM created on the Proxmox node is configured with this MAC and connected
to the corresponding VLAN via the specified bridge.
+
+Upon boot, the VM broadcasts a VLAN-tagged DHCP request, which reaches the
CloudStack Virtual Router (VR) handling that VLAN.
+The VR responds with the appropriate IP address as configured in CloudStack.
Once the VM receives the lease, it becomes fully integrated into the
CloudStack-managed network.
+
+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.
+
+Hyper-V
+^^^^^^
+
+The Hyper-V CloudStack extension is a Python-based script that communicates
with the Hyper-V host using WinRM (Windows Remote Management) over HTTPS,
+using NTLM authentication for secure remote execution of PowerShell commands
that manage the full lifecycle of virtual machines.
+
+Each Hyper-V host maps to a CloudStack host. Before using the Hyper-V
extension, ensure that the Hyper-V host is accessible to the CloudStack
Management Server via WinRM over HTTPS.
+
+Configuring WinRM over HTTPS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Windows Remote Management (WinRM)** is a protocol developed by Microsoft for
securely managing Windows machines remotely using **WS-Management (Web Services
for Management)**.
+It allows remote execution of PowerShell commands over HTTP or HTTPS and is
widely used in automation tools such as **Ansible**, **Terraform**, and
**Packer** for managing Windows infrastructure.
+
+To enable WinRM over HTTPS on the Hyper-V host, ensure the following:
+
+- WinRM is enabled and configured to listen on port 5986 (HTTPS).
+- A valid TLS certificate is installed and bound to the WinRM listener. You
may use a certificate from a trusted Certificate Authority (CA) or a
self-signed certificate.
+- The firewall on the Hyper-V host allows inbound connections on TCP port 5986.
+- The CloudStack Management Server has network access to the Hyper-V host on
port 5986.
+- The Hyper-V host has a local or domain user account with appropriate
permissions for managing virtual machines (e.g., creating, deleting,
configuring VMs).
+
+Sample powershell script to configure WinRM over HTTPS with self-signed TLS
certificate is given below:
+
+.. code-block:: powershell
+
+ Enable-PSRemoting -Force
+ $cert = New-SelfSignedCertificate -DnsName "$env:COMPUTERNAME"
-CertStoreLocation Cert:\LocalMachine\My
+ New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address *
-CertificateThumbprint $cert.Thumbprint -Force
+ New-NetFirewallRule -DisplayName "WinRM HTTPS" -Name "WinRM-HTTPS"
-Protocol TCP -LocalPort 5986 -Direction Inbound -Action Allow
+
+Install pywinrm on CloudStack Management Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**pywinrm** is a Python library that acts as a client to remotely execute
commands on Windows machines via the WinRM protocol. Install it using ``pip3
install pywinrm``.
+
+Host Details
+~~~~~~~~~~~~
+
+Apart from the `url`, `username` and `password`, the following details are
required when adding a Hyper-V host in CloudStack:
+
+* **network_bridge**: Name of the network bridge to use for VM networking.
This bridge must be configured on the Hyper-V host and connected to the
appropriate network interface as explained in the `Configuring Networking`
section below.
+* **vhd_path**: Path to the storage location where VM disks will be created.
+* **vm_path**: Path to the storage location where VM configuration files and
metadata will be stored.
+* **verify_tls_certificate**: Set to `false` to skip TLS certificate
verification for self-signed certificates.
+
+
+Adding Hyper-V to CloudStack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. **Enable extension.** Enable the extension by clicking the `Enable` button
on the `Extensions` page in the UI.
+#. **Create Cluster**. Create a Cluster with hypervisor type `External` and
extension type `HyperV`.
+
+ |hyperv-add-cluster.png|
+
+#. **Add Host.** Add a host to the newly created cluster with the following
details:
+
+ |hyperv-add-host.png|
+
+#. **Create Template.** A Template in CloudStack can map to either a
`Template` or an `ISO` in Hyper-V.
+ Provide a dummy `url` and template name. Select `External` as the
hypervisor and `HyperV` as the extension. Under `External Details`, specify:
+
+ * **template_type**: `template` or `iso`
+ * **generation**: VM generation (1 or 2)
+ * **template_path**: Full path to the template .vhdx file in Proxmox (if
`template_type` is `template`)
+
+ |hyperv-add-template.png|
+
+ * **iso_path**: full path to the ISO in HyperV (if `template_type` is `iso`)
+ * **vhd_size_gb**: Size of the VHD disk to create (in GB) (if
`template_type` is `iso`)
+
+ |hyperv-add-iso.png|
+
+ Note: Templates and ISOs should be stored on shared storage when using
multiple HyperV nodes. Or copy the template/iso to each host's local storage at
the same location.
+
+#. **Deploy Instance.** Deploy an instance using the template created above.
The instance will be provisioned on a randomly selected Hyper-V host.
+ The VM will be configured with the MAC address and VLAN ID as defined in
CloudStack.
+ The VM in Hyper-V is created with the name `'CloudStack instance's internal
name' + '-' + 'CloudStack instance's UUID'` to keep it unique.
+
+#. **Lifecycle operations.** Operations **Start**, **Stop**, **Reboot**, and
**Delete** can be performed on the instance from CloudStack.
+
+#. **Custom actions.** Custom actions **Suspend**, **Resume**, **Create
Snapshot**, **Restore Snapshot**, and **Delete Snapshot** are also supported
for instances.
+
+Configuring Networking
+~~~~~~~~~~~~~~~~~~~~~~
+
+Hyper-V hosts and CloudStack hypervisor hosts must be connected via a VLAN
trunked network.
+On each Hyper-V host, an external virtual switch should be created and bound
to the physical network interface that carries VLAN-tagged traffic.
+This switch must be specified in the Configuration Details (network_bridge)
when adding the Hyper-V host to CloudStack.
+
+When a VM is deployed, CloudStack includes the assigned MAC address and VLAN
ID in the extension payload.
+The VM is then created on the Hyper-V host with this MAC address and attached
to the specified external switch with the corresponding VLAN configured.
+
+Upon boot, the VM sends a VLAN-tagged DHCP request, which reaches the
CloudStack Virtual Router (VR) responsible for that VLAN.
+The VR responds with the correct IP address as configured in CloudStack. Once
the VM receives the lease, it becomes fully integrated into the
CloudStack-managed network.
+
+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.
+
+
+.. _Proxmox VE API: https://pve.proxmox.com/pve-docs/api-viewer/index.html
+
+.. Images
+
+
+.. |built-in-extensions.png| image:: /_static/images/built-in-extensions.png
+.. |proxmox-add-cluster.png| image:: /_static/images/proxmox-add-cluster.png
+.. |proxmox-add-host.png| image:: /_static/images/proxmox-add-host.png
+.. |proxmox-add-token.png| image:: /_static/images/proxmox-add-token.png
+.. |proxmox-api-token-permission.png| image::
/_static/images/proxmox-api-token-permission.png
+.. |proxmox-add-template.png| image:: /_static/images/proxmox-add-template.png
+.. |proxmox-add-iso.png| image:: /_static/images/proxmox-add-iso.png
+.. |proxmox-deploy-instance.png| image::
/_static/images/proxmox-deploy-instance.png
+.. |hyperv-add-cluster.png| image:: /_static/images/hyperv-add-cluster.png
+.. |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
diff --git a/source/adminguide/extensions/custom_actions.rst
b/source/adminguide/extensions/custom_actions.rst
new file mode 100644
index 0000000..c250019
--- /dev/null
+++ b/source/adminguide/extensions/custom_actions.rst
@@ -0,0 +1,62 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+Custom Actions
+^^^^^^^^^^^^^^
+
+In addition to standard instance operations, extensions support custom
actions. These can be configured via UI in the extension details view or the
addCustomAction API. The extension binary or script must implement handlers for
these action names and process any provided parameters.
+
+ |add-custom-action.png|
+
+Description, allowed role types, parameters, success/error messages,
configuration details, timeout can be defined during creation or update.
+Alowed role types can be one or more of Admin, Resource Admin, Domain Admin,
User.
+Success and error messages will be used and returned during action execution.
They allow string expansion and the following can be used to customise messages:
+
+ - {{actionName}} for showing name of the action
+ - {{extensionName}} for showing name of the extension
+ - {{resourceName}} for showing name of the resource
+
+An example usage can be - "Successfully completed {{actionName}} for
{{resourceName}} using {{extensionName}}".
+Configuration details can be key-value pairs which will be passed to the
extension during action execution.
+Timeout value can be configured to adjust wait time for action completion.
+
+A single parameter can have the following details:
+
+ - **name**: Name of the parameter.
+
+ - **type**: Type of the parameter. It can be one of the following: BOOLEAN,
DATE, NUMBER, STRING
+
+ - **validationformat**: Validation format for the parameter value.
Supported only for NUMBER and STRING type. For NUMBER, it can be NONE or
DECIMAL. For STRING, it can be NONE, EMAIL, PASSWORD, URL, UUID.
+
+ - **valueoptions**: Options for the value of the parameter. This is allowed
only for NUMBER and STRING type.
+
+
+Running Custom Action
+~~~~~~~~~~~~~~~~~~~~~
+
+All enabled custom actions can then be triggered for a resource of the type
the action is defined for or provided while running, using the **Run Action**
view or runCustomAction API.
+
+ |run-custom-action-instance.png|
+
+ |run-custom-action.png|
+
+
+.. Images
+
+
+.. |add-custom-action.png| image:: /_static/images/add-custom-action.png
+.. |run-custom-action-instance.png| image::
/_static/images/run-custom-action-instance.png
+.. |run-custom-action.png| image:: /_static/images/run-custom-action.png
diff --git a/source/adminguide/extensions/developer.rst
b/source/adminguide/extensions/developer.rst
new file mode 100644
index 0000000..492c846
--- /dev/null
+++ b/source/adminguide/extensions/developer.rst
@@ -0,0 +1,186 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Writing Extensions for CloudStack
+=================================
+
+The CloudStack Extensions Framework allows developers and operators to write
extensions using any programming language or script. From CloudStack’s
perspective, an extension is simply an executable capable of handling specific
actions and processing input payloads. CloudStack invokes the executable by
passing the action name and the path to a JSON-formatted payload file as
command-line arguments. The extension processes the payload, performs the
required operations on an external system, [...]
+
+
+Create a New Extension
+^^^^^^^^^^^^^^^^^^^^^^
+
+You must first register a new extension using the API or UI:
+
+.. code-block:: bash
+
+ cloudmonkey createExtension name=myext path=myext-executable
+
+Arguments:
+
+- ``name``: Unique name
+- ``path``: Relative path to the executable. Root path will be
`/usr/share/cloudstack-management/extensions/<extension_name>`
+
+The path must be:
+
+- Executable (``chmod +x``)
+- Owned by the ``cloud:cloud`` user
+- Present on all management servers (identical path and binary)
+
+If no explicit path is provided during extension creation, CloudStack will
scaffold a basic shell script at a default location with minimal required
action handlers. This provides a starting point for customization and ensures
the extension is immediately recognized and callable by the system.
+
+CloudStack checks extension readiness periodically and shows its state in the
UI/API.
+
+Extension Structure
+^^^^^^^^^^^^^^^^^^^
+
+Your extension must support the following invocation structure:
+
+.. code-block:: bash
+
+ /path/to/executable <action> <payload_file> <timeout_seconds>
+
+Arguments:
+
+- ``<action>``: Action name (e.g., ``deploy``, ``start``, ``status``)
+- ``<payload_file>``: Path to the input JSON file
+- ``<timeout_seconds>``: Max duration CloudStack will wait for completion
+
+Sample Invocation:
+
+.. code-block:: bash
+
+ /usr/share/cloudstack-management/extensions/myext/myext.py deploy
/var/lib/cloudstack/management/extensions/myext/162345.json 60
+
+Input Format (Payload)
+^^^^^^^^^^^^^^^^^^^^^^
+
+CloudStack provides input via a JSON file, which your executable must read and
parse.
+
+Example:
+
+.. code-block:: json
+
+ {
+ "externaldetails": {
+ "resourcemap": {
+ ...
+ },
+ "virtualmachine": {
+ "exttemplateid": "1"
+ },
+ "host": {
+ ...
+ },
+ "extension": {
+ ...
+ }
+ },
+ "virtualmachineid": "...",
+ "cloudstack.vm.details": {
+ "id": 100,
+ "name": "i-2-100-VM",
+ ...
+ },
+ "virtualmachinename": "i-2-100-VM"
+ }
+
+The schema varies depending on the resource and action. Use this to perform
context-specific logic.
+
+Output Format
+^^^^^^^^^^^^^
+
+Your extension should write a response JSON to ``stdout``. Example:
+
+.. code-block:: json
+
+ {
+ "status": "success",
+ "message": "Deployment completed"
+ }
+
+For custom actions, CloudStack will display the ``message`` in the UI if the
output JSON includes ``"printmessage": "true"``.
+The ``message`` field can be a string, a JSON object or a JSON array.
+
+Action Lifecycle
+^^^^^^^^^^^^^^^^
+
+1. A CloudStack action (e.g., deploy VM) triggers a corresponding extension
action.
+2. CloudStack invokes the extension’s executable with appropriate parameters.
+3. The extension processes the input and responds within the timeout.
+4. CloudStack continues orchestration based on the result.
+
+Custom Actions
+^^^^^^^^^^^^^^
+
+You can define new custom actions for users or admin-triggered workflows.
+
+- Register via UI or ``addCustomAction`` API
+- Define input parameters (name, type, required)
+- Implement the handler for the custom action in your executable.
+
+CloudStack UI will render forms dynamically based on these definitions.
+
+Best Practices
+^^^^^^^^^^^^^^
+
+- Make executable/script idempotent and stateless
+- Validate all inputs before acting
+- Avoid hard dependencies on CloudStack internals
+- Implement logging for troubleshooting
+- Use exit code and ``stdout`` for signaling success/failure
+
+Extension Examples
+^^^^^^^^^^^^^^^^^^
+
+**Bash Example**
+
+.. code-block:: bash
+
+ #!/bin/bash
+ ACTION=$1
+ FILE=$2
+ TIMEOUT=$3
+
+ if [ "$ACTION" == "deploy" ]; then
+ echo '{ "success": true, "result": { "message": "OK" } }'
+ else
+ echo '{ "success": false, "result": { "message": "Unsupported action" }
}'
+ fi
+
+**Python Example**
+
+.. code-block:: python
+
+ import sys, json
+
+ action = sys.argv[1]
+ payload_file = sys.argv[2]
+
+ with open(payload_file) as f:
+ data = json.load(f)
+
+ if action == "deploy":
+ print(json.dumps({"success": True, "result": {"message": "Deployed"}}))
+ else:
+ print(json.dumps({"success": False, "result": {"message": "Unknown
action"}}))
+
+For a clearer understanding of how to implement an extension, developers can
refer to the base shell script scaffolded by CloudStack for orchestrator-type
extensions. This script is located at:
+
+/usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh
+
+It serves as a template with minimal required action handlers, making it a
useful starting point for building new extensions.
+
+Additionally, CloudStack includes built-in extensions for Proxmox and Hyper-V
that demonstrate how to implement extensions in different languages - Bash and
Python.
diff --git a/source/adminguide/extensions/troubleshooting.rst
b/source/adminguide/extensions/troubleshooting.rst
new file mode 100644
index 0000000..815da5d
--- /dev/null
+++ b/source/adminguide/extensions/troubleshooting.rst
@@ -0,0 +1,70 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+Troubleshooting Extensions
+==========================
+
+Validate the Extension Path
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - Ensure that the path is correctly defined and accessible on all
management servers. The executable must be owned by the `cloud` user and group,
and have appropriate permissions to be executed by `cloud:cloud`.
+
+ - The script or binary must be executable and have appropriate permissions.
+
+ - If the binary differs across management servers, the extension will be
marked as Not Ready.
+
+ - Ensure files are stored at:
`/usr/share/cloudstack-management/extensions/<extension_name>`
+
+ - CloudStack runs a background task at regular intervals to verify path
readiness. If the path is not ready, its state will appear as Not Ready in the
UI or API responses.
+
+ - Alerts are generated if the extension path is not ready.
+
+ - The check interval can be configured using the global configuration -
`extension.path.state.check.interval`. The default is 5 minutes.
+
+Verify Payload Handling
+^^^^^^^^^^^^^^^^^^^^^^^
+
+ - Ensure the extension binary can correctly read and parse the incoming
JSON payload.
+
+ - Payload files are placed at:
`/var/lib/cloudstack/management/extensions/<extension_name>/`
+
+ - These payload files are automatically cleaned up after 24 hours.
+
+ - Improper parsing of the payload is a common cause of failure—log any
parsing errors in your extension binary for debugging.
+
+Refer to Base Extension Scripts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - For guidance on implementing supported actions, refer to the base scripts
present for each extension type.
+
+ - For Orchestrator-type extensions, see:
`/usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh`
+
+ - These scripts provide examples of how to handle standard actions like
start, stop, status, etc.
+
+Check Logs for Errors
+^^^^^^^^^^^^^^^^^^^^^
+
+ - If the extension does not respond or returns an error, check the
management server logs.
+
+ - Logs include details of:
+
+ 1. Invocation of the extension binary
+
+ 2. Payload hand-off
+
+ 3. Output parsing
+
+ - Any exceptions or exit code issues.
diff --git a/source/adminguide/index.rst b/source/adminguide/index.rst
index b3d2df8..040ad1c 100644
--- a/source/adminguide/index.rst
+++ b/source/adminguide/index.rst
@@ -190,6 +190,15 @@ Events and Troubleshooting
troubleshooting
+Extensions
+----------
+
+.. toctree::
+ :maxdepth: 4
+
+ extensions
+
+
Best Practices
--------------
