extensions: vnc console access

Related: apache/cloudstack#11601

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

Author: shwstppr

source/adminguide/extensions.rst

@@ -64,7 +64,9 @@ An Orchestrator extension enables CloudStack to delegate VM orchestration to an
 
    - 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.
+   - Instance Lifecycle Support: Orchestrator extensions can handle basic VM actions like prepare, deploy, start, stop, reboot, status and delete.
+
+   - Console Access: Instances can be accessed via VNC consoles. CloudStack retrieves console details from extensions using the ``getconsole`` action, and forwards them to the Console Proxy VM (CPVM) to provide users with console access. Currently, the built-in Proxmox extension supports console access for instances.
 
    - Configuration Details: Key-value configuration details can be specified at different levels - extension, cluster mapping, host, template, service offering, instance.
 

source/adminguide/extensions/developer.rst

@@ -120,7 +120,29 @@ 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.
+4. CloudStack continues action workflow based on the result.
+
+Console Access for Instances with Orchestrator Extensions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Orchestrator extensions can provide console access for instances via VNC.
+To enable this, the extension must implement the ``getconsole`` action and return output in the following JSON format:
+
+.. code-block:: json
+
+    {
+      ...
+      "console": {
+        "host": "pve-node1.internal",
+        "port": "5901",
+        "password": "PVEVNC:6329C6AA::ZPcs5MT....d9",
+        "protocol": "vnc"
+      }
+    }
+
+The returned details are forwarded to the Console Proxy VM (CPVM) running in the same zone as the instance.
+It is required that the specified **host** and **port** are reachable from the CPVM.
+
 
 Custom Actions
 ^^^^^^^^^^^^^^
@@ -183,4 +205,4 @@ For a clearer understanding of how to implement an extension, developers can ref
 
 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.
+Additionally, CloudStack includes in-built extensions for Proxmox and Hyper-V that demonstrate how to implement extensions in different languages - Bash and Python.

source/adminguide/extensions/limitations.rst

@@ -24,8 +24,6 @@ by adding custom actions in the scripts written for the built-in extensions.
 
 **Some general features/actions not supported at the framework level:**
 
-   - Console access to the external Instances.
-
    - Data volumes.
 
    - User Data and Metadata services.
@@ -40,6 +38,8 @@ by adding custom actions in the scripts written for the built-in extensions.
 
    - Add Nics to Instance post deployment.
 
+   - Console access to the in-built Hyper-V orchestrator Instances.
+
 **Actions which can be implemented using Custom Actions in built-in extensions:**
 
    - Reinstall Instance.