[PATCH pve-manager v2 09/17] api: Add endpoint querying available CPU flags cluster-wide

Arthur Bied-Charreton
2026-04-01T08:01:36Z

Add endpoint at `/cluster/qemu/cpu-flags` allowing to query the CPU
flags available on the whole cluster, filtered by acceleration type
(kvm/tcg).

For each flag, a list of nodes supporting it is returned. This gives an
accurate picture of which flags will actually be accepted by QEMU when
starting a VM.

Currently only return available flags for x86_64, see documentation of
query_available_cpu_flags.

Signed-off-by: Arthur Bied-Charreton <a.bied-charreton@proxmox.com>
---
PVE/API2/Cluster.pm | 7 ++++
PVE/API2/Cluster/Makefile | 4 +-
PVE/API2/Cluster/Qemu.pm | 41 +++++++++++++++++++
PVE/API2/Cluster/Qemu/CPUFlags.pm | 68 +++++++++++++++++++++++++++++++
PVE/API2/Cluster/Qemu/Makefile | 17 ++++++++
5 files changed, 136 insertions(+), 1 deletion(-)
create mode 100644 PVE/API2/Cluster/Qemu.pm
create mode 100644 PVE/API2/Cluster/Qemu/CPUFlags.pm
create mode 100644 PVE/API2/Cluster/Qemu/Makefile

diff --git a/PVE/API2/Cluster.pm b/PVE/API2/Cluster.pm
index cc8279ca..4e641a2d 100644
--- a/PVE/API2/Cluster.pm
+++ b/PVE/API2/Cluster.pm
@@ -27,6 +27,7 @@ use PVE::API2::Backup;
use PVE::API2::Cluster::BackupInfo;
use PVE::API2::Cluster::BulkAction;
use PVE::API2::Cluster::Ceph;
+use PVE::API2::Cluster::Qemu;
use PVE::API2::Cluster::Mapping;
use PVE::API2::Cluster::Jobs;
use PVE::API2::Cluster::MetricServer;
@@ -59,6 +60,11 @@ __PACKAGE__->register_method({
path => 'notifications',
});

+__PACKAGE__->register_method({
+ subclass => "PVE::API2::Cluster::Qemu",
+ path => 'qemu',
+});
+
__PACKAGE__->register_method({
subclass => "PVE::API2::ClusterConfig",
path => 'config',
@@ -157,6 +163,7 @@ __PACKAGE__->register_method({
{ name => 'bulk-action' },
{ name => 'ceph' },
{ name => 'config' },
+ { name => 'qemu' },
{ name => 'firewall' },
{ name => 'ha' },
{ name => 'jobs' },
diff --git a/PVE/API2/Cluster/Makefile b/PVE/API2/Cluster/Makefile
index 6cffe4c9..fd33e31d 100644
--- a/PVE/API2/Cluster/Makefile
+++ b/PVE/API2/Cluster/Makefile
@@ -1,13 +1,15 @@
include ../../../defines.mk

SUBDIRS=Mapping \
- BulkAction
+ BulkAction \
+ Qemu

# for node independent, cluster-wide applicable, API endpoints
# ensure we do not conflict with files shipped by pve-cluster!!
PERLSOURCE= \
BackupInfo.pm \
BulkAction.pm \
+ Qemu.pm \
MetricServer.pm \
Mapping.pm \
Notifications.pm \
diff --git a/PVE/API2/Cluster/Qemu.pm b/PVE/API2/Cluster/Qemu.pm
new file mode 100644
index 00000000..ed37fd20
--- /dev/null
+++ b/PVE/API2/Cluster/Qemu.pm
@@ -0,0 +1,41 @@
+package PVE::API2::Cluster::Qemu;
+
+use v5.36;
+
+use PVE::API2::Cluster::Qemu::CPUFlags;
+
+use base qw(PVE::RESTHandler);
+
+__PACKAGE__->register_method({
+ subclass => "PVE::API2::Cluster::Qemu::CPUFlags",
+ path => "cpu-flags",
+});
+
+__PACKAGE__->register_method({
+ name => 'index',
+ path => '',
+ method => 'GET',
+ description => "Cluster index.",
+ permissions => { user => 'all' },
+ parameters => {
+ additionalProperties => 0,
+ properties => {},
+ },
+ returns => {
+ type => 'array',
+ items => {
+ type => "object",
+ properties => {},
+ },
+ links => [{ rel => 'child', href => "{name}" }],
+ },
+ code => sub {
+ my ($param) = @_;
+
+ return [
+ { name => 'cpu-flags' },
+ ];
+ },
+});
+
+1;
diff --git a/PVE/API2/Cluster/Qemu/CPUFlags.pm b/PVE/API2/Cluster/Qemu/CPUFlags.pm
new file mode 100644
index 00000000..a3328e85
--- /dev/null
+++ b/PVE/API2/Cluster/Qemu/CPUFlags.pm
@@ -0,0 +1,68 @@
+package PVE::API2::Cluster::Qemu::CPUFlags;
+
+use v5.36;
+
+use PVE::JSONSchema qw(get_standard_option);
+use PVE::RESTHandler;
+use PVE::Tools qw(extract_param);
+
+use PVE::QemuServer::Helpers;
+use PVE::QemuServer::CPUFlags;
+
+use base qw(PVE::RESTHandler);
+
+__PACKAGE__->register_method({
+ name => 'index',
+ path => '',
+ method => 'GET',
+ description => "List of available CPU flags. Returns an empty list for 'aarch64', "
+ . "PVE does not currently ship a flags list for it.",
+ permissions => { user => 'all' },
+ parameters => {
+ additionalProperties => 0,
+ properties => {
+ arch => get_standard_option('pve-qm-cpu-arch', { optional => 1 }),
+ accel => {
+ description => 'Acceleration type to check node compatibility for.',
+ type => 'string',
+ enum => [qw(kvm tcg)],
+ optional => 1,
+ default => 'kvm',
+ },
+ },
+ },
+ returns => {
+ type => 'array',
+ items => {
+ type => 'object',
+ properties => {
+ name => {
+ type => 'string',
+ description => "Name of the CPU flag.",
+ },
+ description => {
+ type => 'string',
+ description => "Description of the CPU flag.",
+ optional => 1,
+ },
+ 'supported-on' => {
+ description =>
+ 'List of nodes supporting the flag with the selected acceleration type ("accel").',
+ type => 'array',
+ items => get_standard_option('pve-node'),
+ optional => 1,
+ },
+ },
+ },
+ },
+ code => sub {
+ my ($param) = @_;
+
+ my $arch = extract_param($param, 'arch') // PVE::QemuServer::Helpers::get_host_arch();
+ my $accel = extract_param($param, 'accel') // 'kvm';
+
+ return PVE::QemuServer::CPUFlags::query_available_cpu_flags($accel, 0, $arch);
+ },
+});
+
+1;
diff --git a/PVE/API2/Cluster/Qemu/Makefile b/PVE/API2/Cluster/Qemu/Makefile
new file mode 100644
index 00000000..2ab3e0b1
--- /dev/null
+++ b/PVE/API2/Cluster/Qemu/Makefile
@@ -0,0 +1,17 @@
+include ../../../../defines.mk
+
+# for node independent, cluster-wide applicable, API endpoints
+# ensure we do not conflict with files shipped by pve-cluster!!
+PERLSOURCE= \
+ CPUFlags.pm
+
+all:
+
+.PHONY: clean
+clean:
+ rm -rf *~
+
+.PHONY: install
+install: ${PERLSOURCE}
+ install -d ${PERLLIBDIR}/PVE/API2/Cluster/Qemu
+ install -m 0644 ${PERLSOURCE} ${PERLLIBDIR}/PVE/API2/Cluster/Qemu
--
2.47.3