extension/proxmox: add console access for instances (apache#11601)

This PR introduces console access support for instances deployed using Orchestrator Extensions, available via either VNC or a direct URL.

- CloudStack queries the extension using the getconsole action.
- For VNC-based access, the extension must return host/port/ticket details. CloudStack then forwards these to the Console Proxy VM (CPVM) in the instance’s zone. It is assumed that the CPVM can reach the specified host and port.
- For direct URL access, the extension returns a console URL with the protocol set to `direct`. The URL is then provided directly to the user.
- The built-in Proxmox Orchestrator Extension now supports console access via VNC. The extension calls the Proxmox API to fetch console details and returns them in the required format.

Also, adds changes to send caller details to the extension payload.
```
{
  "caller": {
    "roleid": "6b86674b-7e61-11f0-ba77-1e00c8000158",
    "rolename": "Root Admin",
    "name": "admin",
    "roletype": "Admin",
    "id": "93567ed9-7e61-11f0-ba77-1e00c8000158",
    "type": "ADMIN"
  },
  "virtualmachineid": "126f4562-1f0f-4313-875e-6150cabeb72f",
  ...
```

Documentation PR: apache/cloudstack-documentation#560

---------

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

Author: shwstppr

api/src/main/java/org/apache/cloudstack/api/ApiConstants.java

@@ -80,6 +80,7 @@ public class ApiConstants {
     public static final String BYTES_WRITE_RATE_MAX = "byteswriteratemax";
     public static final String BYTES_WRITE_RATE_MAX_LENGTH = "byteswriteratemaxlength";
     public static final String BYPASS_VLAN_OVERLAP_CHECK = "bypassvlanoverlapcheck";
+    public static final String CALLER = "caller";
     public static final String CAPACITY = "capacity";
     public static final String CATEGORY = "category";
     public static final String CAN_REVERT = "canrevert";

api/src/main/java/org/apache/cloudstack/api/command/user/consoleproxy/CreateConsoleEndpointCmd.java

@@ -35,6 +35,7 @@
 import org.apache.cloudstack.context.CallContext;
 import org.apache.cloudstack.utils.consoleproxy.ConsoleAccessUtils;
 import org.apache.commons.collections.MapUtils;
+import org.apache.commons.lang3.ObjectUtils;
 
 import javax.inject.Inject;
 import java.util.Map;
@@ -86,6 +87,10 @@ private CreateConsoleEndpointResponse createResponse(ConsoleEndpoint endpoint) {
     }
 
     private ConsoleEndpointWebsocketResponse createWebsocketResponse(ConsoleEndpoint endpoint) {
+        if (ObjectUtils.allNull(endpoint.getWebsocketHost(), endpoint.getWebsocketPort(), endpoint.getWebsocketPath(),
+                endpoint.getWebsocketToken(), endpoint.getWebsocketExtra())) {
+            return null;
+        }
         ConsoleEndpointWebsocketResponse wsResponse = new ConsoleEndpointWebsocketResponse();
         wsResponse.setHost(endpoint.getWebsocketHost());
         wsResponse.setPort(endpoint.getWebsocketPort());

core/src/main/java/com/cloud/agent/api/GetExternalConsoleAnswer.java

@@ -0,0 +1,68 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package com.cloud.agent.api;
+
+public class GetExternalConsoleAnswer extends Answer {
+
+    private String url;
+    private String host;
+    private Integer port;
+    @LogLevel(LogLevel.Log4jLevel.Off)
+    private String password;
+    private String protocol;
+    private boolean passwordOneTimeUseOnly;
+
+    public GetExternalConsoleAnswer(Command command, String details) {
+        super(command, false, details);
+    }
+
+    public GetExternalConsoleAnswer(Command command, String url, String host, Integer port, String password,
+                    boolean passwordOneTimeUseOnly, String protocol) {
+        super(command, true, "");
+        this.url = url;
+        this.host = host;
+        this.port = port;
+        this.password = password;
+        this.passwordOneTimeUseOnly = passwordOneTimeUseOnly;
+        this.protocol = protocol;
+    }
+
+    public String getUrl() {
+        return url;
+    }
+
+    public String getHost() {
+        return host;
+    }
+
+    public Integer getPort() {
+        return port;
+    }
+
+    public String getPassword() {
+        return password;
+    }
+
+    public String getProtocol() {
+        return protocol;
+    }
+
+    public boolean isPasswordOneTimeUseOnly() {
+        return passwordOneTimeUseOnly;
+    }
+}

core/src/main/java/com/cloud/agent/api/GetExternalConsoleCommand.java

@@ -0,0 +1,53 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package com.cloud.agent.api;
+
+import com.cloud.agent.api.to.VirtualMachineTO;
+
+public class GetExternalConsoleCommand extends Command {
+    String vmName;
+    VirtualMachineTO vm;
+    protected boolean executeInSequence;
+
+    public GetExternalConsoleCommand(String vmName, VirtualMachineTO vm) {
+        this.vmName = vmName;
+        this.vm = vm;
+        this.executeInSequence = false;
+    }
+
+    public String getVmName() {
+        return this.vmName;
+    }
+
+    public void setVirtualMachine(VirtualMachineTO vm) {
+        this.vm = vm;
+    }
+
+    public VirtualMachineTO getVirtualMachine() {
+        return vm;
+    }
+
+    @Override
+    public boolean executeInSequence() {
+        return executeInSequence;
+    }
+
+    public void setExecuteInSequence(boolean executeInSequence) {
+        this.executeInSequence = executeInSequence;
+    }
+}

core/src/main/java/com/cloud/agent/api/RunCustomActionCommand.java

@@ -21,10 +21,12 @@
 
 import java.util.Map;
 
+import com.cloud.agent.api.to.VirtualMachineTO;
+
 public class RunCustomActionCommand extends Command {
 
     String actionName;
-    Long vmId;
+    VirtualMachineTO vmTO;
     Map<String, Object> parameters;
 
     public RunCustomActionCommand(String actionName) {
@@ -36,12 +38,12 @@ public String getActionName() {
         return actionName;
     }
 
-    public Long getVmId() {
-        return vmId;
+    public VirtualMachineTO getVmTO() {
+        return vmTO;
     }
 
-    public void setVmId(Long vmId) {
-        this.vmId = vmId;
+    public void setVmTO(VirtualMachineTO vmTO) {
+        this.vmTO = vmTO;
     }
 
     public Map<String, Object> getParameters() {

engine/components-api/src/main/java/com/cloud/hypervisor/ExternalProvisioner.java

@@ -18,6 +18,8 @@
 
 import java.util.Map;
 
+import com.cloud.agent.api.GetExternalConsoleAnswer;
+import com.cloud.agent.api.GetExternalConsoleCommand;
 import com.cloud.agent.api.HostVmStateReportEntry;
 import com.cloud.agent.api.PrepareExternalProvisioningAnswer;
 import com.cloud.agent.api.PrepareExternalProvisioningCommand;
@@ -57,5 +59,7 @@ public interface ExternalProvisioner extends Manager {
 
     Map<String, HostVmStateReportEntry> getHostVmStateReport(long hostId, String extensionName, String extensionRelativePath);
 
+    GetExternalConsoleAnswer getInstanceConsole(String hostGuid, String extensionName, String extensionRelativePath, GetExternalConsoleCommand cmd);
+
     RunCustomActionAnswer runCustomAction(String hostGuid, String extensionName, String extensionRelativePath, RunCustomActionCommand cmd);
 }

extensions/HyperV/hyperv.py

@@ -25,7 +25,7 @@
 
 
 def fail(message):
-    print(json.dumps({"error": message}))
+    print(json.dumps({"status": "error", "error": message}))
     sys.exit(1)
 
 
@@ -220,6 +220,9 @@ def delete(self):
                 fail(str(e))
         succeed({"status": "success", "message": "Instance deleted"})
 
+    def get_console(self):
+        fail("Operation not supported")
+
     def suspend(self):
         self.run_ps(f'Suspend-VM -Name "{self.data["vmname"]}"')
         succeed({"status": "success", "message": "Instance suspended"})
@@ -283,6 +286,7 @@ def main():
         "reboot": manager.reboot,
         "delete": manager.delete,
         "status": manager.status,
+        "getconsole": manager.get_console,
         "suspend": manager.suspend,
         "resume": manager.resume,
         "listsnapshots": manager.list_snapshots,

extensions/Proxmox/proxmox.sh

@@ -18,7 +18,7 @@
 
 parse_json() {
     local json_string="$1"
-    echo "$json_string" | jq '.' > /dev/null || { echo '{"error":"Invalid JSON input"}'; exit 1; }
+    echo "$json_string" | jq '.' > /dev/null || { echo '{"status": "error", "error": "Invalid JSON input"}'; exit 1; }
 
     local -A details
     while IFS="=" read -r key value; do
@@ -112,9 +112,14 @@ call_proxmox_api() {
       curl_opts+=(-d "$data")
     fi
 
-    #echo curl "${curl_opts[@]}" "https://${url}:8006/api2/json${path}" >&2
     response=$(curl "${curl_opts[@]}" "https://${url}:8006/api2/json${path}")
+    local status=$?
+    if [[ $status -ne 0 ]]; then
+        echo "{\"errors\":{\"curl\":\"API call failed with status $status: $(echo "$response" | jq -Rsa . | jq -r .)\"}}"
+        return $status
+    fi
     echo "$response"
+    return 0
 }
 
 wait_for_proxmox_task() {
@@ -129,7 +134,7 @@ wait_for_proxmox_task() {
         local now
         now=$(date +%s)
         if (( now - start_time > timeout )); then
-            echo '{"error":"Timeout while waiting for async task"}'
+            echo '{"status": "error", "error":"Timeout while waiting for async task"}'
             exit 1
         fi
 
@@ -139,7 +144,7 @@ wait_for_proxmox_task() {
         if [[ -z "$status_response" || "$status_response" == *'"errors":'* ]]; then
             local msg
             msg=$(echo "$status_response" | jq -r '.message // "Unknown error"')
-            echo "{\"error\":\"$msg\"}"
+            echo "{\"status\": \"error\", \"error\": \"$msg\"}"
             exit 1
         fi
 
@@ -285,6 +290,86 @@ status() {
     echo "{\"status\": \"success\", \"power_state\": \"$powerstate\"}"
 }
 
+get_node_host() {
+    check_required_fields node
+    local net_json host
+
+    if ! net_json="$(call_proxmox_api GET "/nodes/${node}/network")"; then
+        echo ""
+        return 1
+    fi
+
+    # Prefer a static non-bridge IP
+    host="$(echo "$net_json" | jq -r '
+        .data
+        | map(select(
+            (.type // "") != "bridge" and
+            (.type // "") != "bond" and
+            (.method // "") == "static" and
+            ((.address // .cidr // "") != "")
+        ))
+        | map(.address // (.cidr | split("/")[0]))
+        | .[0] // empty
+    ' 2>/dev/null)"
+
+    # Fallback: first interface with a CIDR
+    if [[ -z "$host" ]]; then
+        host="$(echo "$net_json" | jq -r '
+            .data
+            | map(select((.cidr // "") != ""))
+            | map(.cidr | split("/")[0])
+            | .[0] // empty
+        ' 2>/dev/null)"
+    fi
+
+    echo "$host"
+}
+
+ get_console() {
+     check_required_fields node vmid
+
+     local api_resp port ticket
+     if ! api_resp="$(call_proxmox_api POST "/nodes/${node}/qemu/${vmid}/vncproxy")"; then
+         echo "$api_resp" | jq -c '{status:"error", error:(.errors.curl // (.errors|tostring))}'
+         exit 1
+     fi
+
+     port="$(echo "$api_resp"   | jq -re '.data.port // empty' 2>/dev/null || true)"
+     ticket="$(echo "$api_resp" | jq -re '.data.ticket // empty' 2>/dev/null || true)"
+
+     if [[ -z "$port" || -z "$ticket" ]]; then
+         jq -n --arg raw "$api_resp" \
+             '{status:"error", error:"Proxmox response missing port/ticket", upstream:$raw}'
+         exit 1
+     fi
+
+     # Derive host from node’s network info
+     local host
+     host="$(get_node_host)"
+     if [[ -z "$host" ]]; then
+         jq -n --arg msg "Could not determine host IP for node $node" \
+             '{status:"error", error:$msg}'
+         exit 1
+     fi
+
+     jq -n \
+         --arg host "$host" \
+         --arg port "$port" \
+         --arg password "$ticket" \
+         --argjson passwordonetimeuseonly true \
+         '{
+             status: "success",
+             message: "Console retrieved",
+             console: {
+                 host: $host,
+                 port: $port,
+                 password: $password,
+                 passwordonetimeuseonly: $passwordonetimeuseonly,
+                 protocol: "vnc"
+             }
+         }'
+ }
+
 list_snapshots() {
     snapshot_response=$(call_proxmox_api GET "/nodes/${node}/qemu/${vmid}/snapshot")
     echo "$snapshot_response" | jq '
@@ -356,7 +441,12 @@ parameters_file="$2"
 wait_time=$3
 
 if [[ -z "$action" || -z "$parameters_file" ]]; then
-    echo '{"error":"Missing required arguments"}'
+    echo '{"status": "error", "error": "Missing required arguments"}'
+    exit 1
+fi
+
+if [[ ! -r "$parameters_file" ]]; then
+    echo '{"status": "error", "error": "File not found or unreadable"}'
     exit 1
 fi
 
@@ -396,6 +486,9 @@ case $action in
     status)
         status
         ;;
+    getconsole)
+        get_console
+        ;;
     ListSnapshots)
         list_snapshots
         ;;
@@ -409,7 +502,7 @@ case $action in
         delete_snapshot
         ;;
     *)
-        echo '{"error":"Invalid action"}'
+        echo '{"status": "error", "error": "Invalid action"}'
         exit 1
         ;;
 esac