extensions: instance console access

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 either via VNC consoles or through a direct URL, depending on the capabilities of the orchestrator extension. CloudStack retrieves console details from extensions using the ``getconsole`` action and either forwards them to the Console Proxy VM (CPVM) (for VNC access) or provides the direct console URL to the user. Out of the box, only 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,48 @@ 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 either through **VNC** or a **direct URL**.
+To enable this, the extension must implement the ``getconsole`` action and return output in one of the following JSON formats:
+
+VNC-based console:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      ...
+      "console": {
+        "host": "pve-node1.internal",
+        "port": "5901",
+        "password": "PVEVNC:6329C6AA::ZPcs5MT....d9",
+        "protocol": "vnc"
+      }
+    }
+
+For VNC-based access, the returned details are forwarded to the Console Proxy VM (CPVM) in the same zone as the instance. The specified **host** and **port** must be reachable from the CPVM.  
+
+Direct URL-based console:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      ...
+      "console": {
+        "url": "CONSOLE_URL",
+        "protocol": "direct"
+      }
+    }
+
+
+.. note::
+   For direct URL–based console access, CloudStack does not report the acquired or client IP address.
+   In this mode, security and access control must be handled by the server providing the console.
 
 Custom Actions
 ^^^^^^^^^^^^^^
@@ -183,4 +224,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 for instances using the built-in Hyper-V orchestrator is not available out of the box.
+
 **Actions which can be implemented using Custom Actions in built-in extensions:**
 
    - Reinstall Instance.