notes on writing extensions

Signed-off-by: Abhishek Kumar <[email protected]>

Author: shwstppr

source/adminguide/extensions.rst

@@ -84,6 +84,8 @@ CloudStack provides sample built-in orchestrator extensions for demonstration an
 
 .. include:: extensions/troubleshooting.rst
 
+.. include:: extensions/developer.rst
+
 .. Images
 
 

source/adminguide/extensions/developer.rst

@@ -0,0 +1,156 @@
+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, and returns the result as a JSON response written to `stdout`.
+
+
+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 /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
+
+   {
+     "resourceType": "VM",
+     "resourceUuid": "2b3c3e54-1ef3-4b8b-941d-61a1adcc7fa2",
+     "action": "deploy",
+     "accessDetails": {
+       "username": "admin",
+       "apiKey": "ABCD1234"
+     }
+   }
+
+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 may use the response to show it in the UI.
+
+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.