diff --git a/source/adminguide/extensions.rst b/source/adminguide/extensions.rst index 071d6c688a..10fe360eae 100644 --- a/source/adminguide/extensions.rst +++ b/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 `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. diff --git a/source/adminguide/extensions/developer.rst b/source/adminguide/extensions/developer.rst index 492c846cae..cd9bc976b4 100644 --- a/source/adminguide/extensions/developer.rst +++ b/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. diff --git a/source/adminguide/extensions/inbuilt_extensions.rst b/source/adminguide/extensions/inbuilt_extensions.rst index 758941fce6..34df6507f3 100644 --- a/source/adminguide/extensions/inbuilt_extensions.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/adminguide/extensions/limitations.rst b/source/adminguide/extensions/limitations.rst index a0b74d3481..d043565b79 100644 --- a/source/adminguide/extensions/limitations.rst +++ b/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.