This is an automated email from the ASF dual-hosted git repository.
shwstppr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new d80ffb28 extensions: instance console access (#560)
d80ffb28 is described below
commit d80ffb28efcdf8098302a726a9319edf6b1e09ad
Author: Abhishek Kumar <[email protected]>
AuthorDate: Sat Sep 27 08:56:11 2025 +0530
extensions: instance console access (#560)
Notes about console access for Orchestrator extension instances.
Related: apache/cloudstack#11601
---------
Signed-off-by: Abhishek Kumar <[email protected]>
---
source/adminguide/extensions.rst | 4 +-
source/adminguide/extensions/developer.rst | 60 ++++++++++++++++++++--
.../adminguide/extensions/inbuilt_extensions.rst | 11 ++++
source/adminguide/extensions/limitations.rst | 2 -
4 files changed, 71 insertions(+), 6 deletions(-)
diff --git a/source/adminguide/extensions.rst b/source/adminguide/extensions.rst
index 071d6c68..10fe360e 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 [...]
- 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 492c846c..cd9bc976 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 758941fc..34df6507 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 a0b74d34..d043565b 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.
