Allow multiple simultaneous console viewers for KVM user VMs

[Ericreeses]

Description

This PR adds support for multiple simultaneous console viewers for the same KVM user VM.

Currently, console proxy sessions for a VM use the VM client tag as the viewer key. When a second user opens the console for the same VM, the existing viewer is replaced and the first user's console session is disconnected.

CloudStack already supports using a unique console session UUID as the viewer key when sessionRequiresNewViewer is enabled. This change exposes that existing capability for KVM user VMs through a new global setting:

consoleproxy.kvm.multiple.viewers.enabled

The setting defaults to false, preserving the existing single-viewer behavior.

When enabled for a KVM user VM, each console request uses a unique viewer session, allowing multiple users to access the same VM console simultaneously.

The change is limited to KVM user VMs. System VMs and other hypervisors retain their existing console behavior.

Fixes: #13869

Types of changes

• Breaking change (fix or feature that would cause existing functionality to change)
• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Enhancement (improves an existing feature and functionality)
• Cleanup (Code refactoring and cleanup, that may add test cases)
• Build/CI
• Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

• Major
• Minor

Bug Severity

• BLOCKER
• Critical
• Major
• Minor
• Trivial

Screenshots (if appropriate)

N/A

How Has This Been Tested?

Unit tests were added to ConsoleAccessManagerImplTest covering:

• KVM user VM with multiple console viewers enabled: a new viewer is required.
• KVM user VM with multiple console viewers disabled: existing single-viewer behavior is preserved.
• KVM system VM: multiple-viewer behavior is not applied and the setting is not consulted.

Focused unit test:

mvn -pl server -Dtest=ConsoleAccessManagerImplTest test

Result:

Tests run: 39, Failures: 0, Errors: 0, Skipped: 0

BUILD SUCCESS

The CloudStack CI-style build was also executed:

mvn -B -P developer,systemvm -Dsimulator -Dnoredist clean install -T$(nproc)

Result:

BUILD SUCCESS

The feature was additionally validated manually with CloudStack 4.22.1.0 and KVM. With the existing behavior, opening the same VM console from a second user disconnects the first user. After enabling per-session viewers, two users were able to remain connected to the same KVM VM console simultaneously.

How did you try to break this feature and the system with this change?

The global setting defaults to false, and unit testing verifies that the existing single-viewer behavior remains unchanged when it is disabled.

The feature is explicitly restricted to KVM user VMs. The feature is explicitly restricted to KVM user VMs. A unit test verifies that KVM system VMs do not receive the new viewer behavior and that the multiple-viewer setting is not consulted.

Existing Hyper-V and external-console tests in ConsoleAccessManagerImplTest also continue to pass.

The complete CloudStack developer/systemvm simulator build passed after the change.

Reviewer Test Procedure

1. Deploy the change to a CloudStack environment using KVM.
2. In Global Settings, locate:
   consoleproxy.kvm.multiple.viewers.enabled
3. Set the value to true.
4. Open the console of the same running KVM user VM from two separate CloudStack user sessions or browser sessions.
5. Verify that:
   • Both console sessions remain connected.
   • Opening the second console does not disconnect the first.
   • Both users can view the same VM console.
   • Keyboard and mouse input continue to function from both sessions.
6. Close one of the console sessions and verify that the other session remains connected.
7. Open another console session for the same VM and verify that it can connect without disconnecting the existing viewer.
8. Set consoleproxy.kvm.multiple.viewers.enabled back to false.
9. Open two fresh console sessions for the same KVM user VM.
10. Verify that the existing single-viewer behavior is restored: opening the second console replaces/disconnects the first viewer.
11. Optionally verify that enabling the setting does not change console behavior for KVM system VMs or non-KVM hypervisors.

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache CloudStack community! If you have any issues or are unsure about any anything please check our Contribution Guide (https://github.com/apache/cloudstack/blob/main/CONTRIBUTING.md)
Here are some useful points:

• In case of a new feature add useful documentation (raise doc PR at https://github.com/apache/cloudstack-documentation)
• Be patient and persistent. It might take some time to get a review or get the final approval from the committers.
• Pay attention to the quality of your code, ensure tests are passing and your PR doesn't have conflicts.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Issues, Mailing list and Slack.
• Be sure to read the CloudStack Coding Conventions.
  Apache CloudStack is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@cloudstack.apache.org (https://cloudstack.apache.org/mailing-lists.html)
  Slack: https://apachecloudstack.slack.com/

[Copilot]

Pull request overview

This PR adds an opt-in global configuration to allow multiple simultaneous console viewers for KVM user VMs by forcing each console request to require a new viewer session (unique session UUID), while leaving system VMs and other hypervisors unchanged.

Changes:

• Introduces global setting consoleproxy.kvm.multiple.viewers.enabled and exposes it via ConsoleAccessManager config keys.
• Updates KVM console-connection detail generation to set sessionRequiresNewViewer=true only for KVM + User VM when the setting is enabled.
• Adds unit tests and release notes for the new behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
api/src/main/java/org/apache/cloudstack/consoleproxy/ConsoleAccessManager.java	Adds the new global ConfigKey for enabling multiple KVM console viewers.
server/src/main/java/org/apache/cloudstack/consoleproxy/ConsoleAccessManagerImpl.java	Registers the new config key and applies sessionRequiresNewViewer for KVM user VMs when enabled.
server/src/test/java/org/apache/cloudstack/consoleproxy/ConsoleAccessManagerImplTest.java	Adds unit tests for the new KVM user VM behavior and expected non-effect on KVM system VMs.
PendingReleaseNotes	Documents the new global setting and its default behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 62.50000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 19.64%. Comparing base (659f675) to head (7abc435).

Files with missing lines	Patch %	Lines
...udstack/consoleproxy/ConsoleAccessManagerImpl.java	57.14%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##               main   #13870   +/-   ##
=========================================
  Coverage     19.64%   19.64%           
- Complexity    19790    19791    +1     
=========================================
  Files          6368     6368           
  Lines        574889   574897    +8     
  Branches      70353    70356    +3     
=========================================
+ Hits         112962   112967    +5     
  Misses       449656   449656           
- Partials      12271    12274    +3     

Flag	Coverage Δ
uitests	3.41% <ø> (ø)
unittests	20.92% <62.50%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nvazquez]

Code LGTM - seems like this functionality has been added since the extensions support for console proxy, so externalizing it into a disabled by default global setting makes sense to me. Haven't tested it yet