extensions: instance console access (#560)

Notes about console access for Orchestrator extension instances.
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 Supported: 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 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 external console URL to the user. Since 4.22.0, out-of-the-box console access support is available for instances deployed using the in-built Proxmox extension. See :ref:`Console Access for Instances with Orchestrator Extensions <console-access-for-instances-with-orchestrator-extensions>`for details on adding console access support in developed extensions.
 
    - 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

@@ -94,7 +94,15 @@ Example:
        "name": "i-2-100-VM",
        ...
      },
-     "virtualmachinename": "i-2-100-VM"
+     "virtualmachinename": "i-2-100-VM",
+     "caller": {
+       "roleid": "6b86674b-7e61-11f0-ba77-1e00c8000158",
+       "rolename": "Root Admin",
+       "name": "admin",
+       "roletype": "Admin",
+       "id": "93567ed9-7e61-11f0-ba77-1e00c8000158",
+       "type": "ADMIN"
+     }
    }
 
 The schema varies depending on the resource and action. Use this to perform context-specific logic.
@@ -120,7 +128,53 @@ 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 **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",
+        "passwordonetimeuseonly": true
+        "protocol": "vnc"
+      }
+    }
+
+``passwordonetimeuseonly`` is optional. It can be set to ``true`` if the system returns a one-time-use VNC ticket.
+
+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 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.
+
+   Protocol value of ``direct`` can be used for URL–based console access.
 
 Custom Actions
 ^^^^^^^^^^^^^^
@@ -183,4 +237,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/inbuilt_extensions.rst

@@ -33,6 +33,15 @@ The Proxmox CloudStack Extension is written in shell script and communicates wit
 
 Before using the Proxmox Extension, ensure that the Proxmox Datacenter is configured correctly and accessible to CloudStack.
 
+Since 4.22.0, console access support is available for instances deployed using the in-built Proxmox extension via VNC and console proxy VM.
+
+.. note::
+   Proxmox VNC connections have a short initial connection timeout (about 10 seconds),
+   even when accessing the console from the CloudStack UI. If the noVNC interface takes
+   longer to load, or if there is a delay between creating the console endpoint and
+   opening it, the connection may fail on the first attempt. In such cases, users can
+   simply retry to establish the console session.
+
 Get the API Token-Secret from Proxmox
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -161,6 +170,8 @@ using NTLM authentication for secure remote execution of PowerShell commands tha
 
 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.
 
+Console access for instances deployed using the Hyper-V extension is not available out of the box.
+
 Configuring WinRM over HTTPS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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.