[Feature] Add latest OS versions to guest OS list

[la-wu]

The required feature described as a wish

As an MSP switching from vmware to cloudstack at the moment we would love to see the latest Linux versions within the Guest OS list by default. Currently Alma/Rocky etc. are on version 9, debian latest is 12, ubuntu latest is 24. All of them have one newer Major version not sure about other distributions.

I know we can add all these manual. But would be nice to have them in the default to have no issues wit future cloudstack updates.

[github-actions[bot]]

🎯 Triage report

Feature request to expand the default Guest OS list with newer major versions of common Linux distributions (AlmaLinux/Rocky 10, Debian 13, Ubuntu newer LTS, etc.) so admins don't need to add them manually after each release.

📊 Assessment

Dimension	Value	Reasoning
Type	type:new-feature	Requests new default data (guest OS mappings), not a bug fix
Component	none	Affects the guest OS type list, which spans management-server config data rather than a single clearly identifiable component
Severity	n/a	Not a bug
Labels	type:new-feature	See above
Coding agent	Needs more info	The general idea is clear, but a concrete PR would require enumerating exact distro/version/hypervisor guest-OS-mapping entries to add (per hypervisor: KVM, VMware, XenServer), which isn't specified here

🔗 Similar issues

• Support Debian 13 (trixie) #12374 (related) — explicit request to add Debian 13 (trixie) support to the guest OS list, a subset of this broader request

💡 Notes and suggestions

• The default guest OS list is defined in DB seed data (e.g. engine/schema/src/main/resources/META-INF/db/schema-* and guest_os/guest_os_hypervisor tables) — historically new OS types are added via SQL upgrade scripts per major release.
• Consider asking the reporter to specify exactly which OS/version combinations they need (e.g. AlmaLinux 10, Rocky Linux 10, Ubuntu 24.04 already exists per issue text, Ubuntu 25.x, Debian 13) and for which hypervisors, to scope a concrete PR.
• Related discussion in Support Debian 13 (trixie) #12374 shows there is an established process/precedent for adding a single new guest OS via a dedicated PR — this issue could be split into per-OS sub-tasks following that pattern.

Generated by Daily Issue Triage · sonnet50 71.2K · ◷

Add this agentic workflows to your repo

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-issue-triage.md@d7c1dc4b72b00607a67caaffdcc216cb64379cf9

[DaanHoogland]

@la-wu , there are APIs to define newer guest OSses. the project can not predict which newer versions will come out and when. Not reliably anyway. You could write yourself a script that adds guest OSses as soon as you have templates available.

Maybe in a later stage such a workflow can be integrated, but it is too unclear now. This is why @nvazquez added the needs-functional-definition label, and I agree with him.

I am converting this to a discussion item. You can start a new issue if you have a more implementable description of your requirement or discuss how that would look in the discussion.

[weizhouapache]

New guest OS versions are generally not a problem with KVM hypervisors. However, they may cause unexpected issues for users running VMware or XenServer/XCP-ng.

For example, Ubuntu 26.04 may not be supported by some older VMware or XenServer/XCP-ng versions. If a template is registered with the guest OS type set to Ubuntu 26.04, the hypervisor might recognise it as Other Linux or a similar generic OS type, which could lead to some operations being unexpectedly disallowed.

If the template is registered as Ubuntu 24.04, compatibility is likely to be better, as it has been available for two years and is well supported by recent VMware and XenServer/XCP-ng releases.

[la-wu]

Hi guys,
thanks for your feedback I understand the issue it could have with none KVM installations.
As I said I am fine with adding them manually. But it would make life easier to have new version within base installation as you don`t need to worry about updates, as stated in documentation:
https://docs.cloudstack.apache.org/en/latest/upgrading/upgrade/_customisation_warnings.html#guest-os-mappings

For us it would be enough to add Ubuntu 26, Debian 13, Rocky Linux 10 for KVM Hosts.

If I understand the process to have a Guest OS Type listed within default installation it is done within the shema update SQL script. Like here with Rocky 9 etc.:
https://github.com/apache/cloudstack/blob/main/engine/schema/src/main/resources/META-INF/db/schema-41720to41800.sql#L27

So it would be something like:
-- Add Rocky Linux 10 guest OS mapping
CALL ADD_GUEST_OS_AND_HYPERVISOR_MAPPING (
(SELECT id FROM cloud.guest_os_category WHERE name = 'Rocky Linux'),
'Rocky Linux 10', 'KVM', 'default', 'Rocky Linux 10'
);

But as I am quite new to cloudstack I am not sure if there is anything more to think if when you add this.

[DaanHoogland]

https://cloudstack.apache.org/api/apidocs-4.23/apis/addGuestOs.html
https://cloudstack.apache.org/api/apidocs-4.23/apis/addGuestOsMapping.html

look in https://cloudstack.apache.org/api/apidocs-4.23/ for any related API calls that might help as well. I would avoid the SQL versions.

[la-wu]

Hi Daan,
I am aware of the possibility to add all needed guest OS version on my own.
I am just afraid of issues after Cloudstack version updates when the added versions are getting default version with the update.

Is there any guideline when guest OS version are added to Cloudstack versions ?

[DaanHoogland]

usually as soon as they have been confirmed to work, So we'd need a user to confirm them.

[nickaccuweb]

@la-wu

Yes, your understanding is correct. CloudStack uses version-specific database upgrade scripts to introduce new Guest OS types and their corresponding hypervisor mappings. The ADD_GUEST_OS_AND_HYPERVISOR_MAPPING procedure handles both entries, so your approach is similar to what has been done for previous OS versions.

There is one small correction to your SQL example. CloudStack currently uses the CentOS category (ID 1) for Rocky Linux, rather than having a separate Rocky Linux category.

For an upstream schema upgrade, the entry would look like this:

CALL ADD_GUEST_OS_AND_HYPERVISOR_MAPPING (1, 'Rocky Linux 10', 'KVM', 'default', 'Rocky Linux 10');

A similar approach could be used for Debian 13 and Ubuntu 26.04 LTS, using their respective OS categories.

However, I would suggest a few things before submitting these changes:

1. Add the mappings through a pull request against the appropriate upcoming CloudStack schema upgrade script, rather than modifying an existing released script.
2. Verify that the guest OS types work properly with KVM by testing template registration, VM deployment, startup, reboot and basic VM operations.
3. Check that the new mappings do not conflict with existing Guest OS entries or mappings.

There is also an existing [PR #13465](#13465) for Ubuntu 26.04 LTS. It is still in draft because the maintainers want to address how Guest OS types are exposed to different hypervisors. It would be worth reviewing that PR before making similar changes.

For your current installation, I would recommend using the addGuestOs and addGuestOsMapping APIs instead of making direct database changes. As mentioned in the upgrade documentation, manually added mappings can conflict with mappings introduced by future releases, so they need to be handled carefully before upgrading.

If your main goal is to have these versions available by default without maintaining custom mappings, contributing the tested KVM mappings upstream would be the better long-term solution.

Since you are specifically targeting KVM, including your test results with the proposed changes should also help the maintainers review them.

Regards,
Nick R
AccuWeb.Cloud

[weizhouapache]

@la-wu
if you are not comfortable with the APIs (suggested by @DaanHoogland ), you can use the SQL procedure.

Please note, if you use another hypervisor (not KVM) or mixed hypervisors , do NOT run it !

for example, your SQL below is good for KVM I think,

-- Add Rocky Linux 10 guest OS mapping
CALL ADD_GUEST_OS_AND_HYPERVISOR_MAPPING (
(SELECT id FROM cloud.guest_os_category WHERE name = 'Rocky Linux'),
'Rocky Linux 10', 'KVM', 'default', 'Rocky Linux 10'
);

run results

mysql> CALL ADD_GUEST_OS_AND_HYPERVISOR_MAPPING (
    -> (SELECT id FROM cloud.guest_os_category WHERE name = 'Rocky Linux'),
    -> 'Rocky Linux 10', 'KVM', 'default', 'Rocky Linux 10'
    -> );
Query OK, 1 row affected (0.07 sec)

mysql> select * from guest_os where display_name='Rocky Linux 10';
+-----+-------------+------+--------------------------------------+----------------+---------------------+---------+-----------------+---------+
| id  | category_id | name | uuid                                 | display_name   | created             | removed | is_user_defined | display |
+-----+-------------+------+--------------------------------------+----------------+---------------------+---------+-----------------+---------+
| 383 |          13 | NULL | 77057b34-e003-11f1-8271-1e00b5000454 | Rocky Linux 10 | 2026-11-14 08:14:51 | NULL    |               0 |       1 |
+-----+-------------+------+--------------------------------------+----------------+---------------------+---------+-----------------+---------+
1 row in set (0.01 sec)

mysql> select * from guest_os_hypervisor where guest_os_id=383;
+-------+-----------------+----------------+-------------+--------------------+--------------------------------------+---------------------+---------+-----------------+
| id    | hypervisor_type | guest_os_name  | guest_os_id | hypervisor_version | uuid                                 | created             | removed | is_user_defined |
+-------+-----------------+----------------+-------------+--------------------+--------------------------------------+---------------------+---------+-----------------+
| 10717 | KVM             | Rocky Linux 10 |         383 | default            | 77067148-e003-11f1-8271-1e00b5000454 | 2026-11-14 08:14:51 | NULL    |               0 |
+-------+-----------------+----------------+-------------+--------------------+--------------------------------------+---------------------+---------+-----------------+
1 row in set (0.00 sec)

fyi, known guest os categories on my testing env (checked on other envs too):

mysql> select * from guest_os_category;
+----+-------------+--------------------------------------+----------+----------+---------+---------------------+
| id | name        | uuid                                 | featured | sort_key | created | removed             |
+----+-------------+--------------------------------------+----------+----------+---------+---------------------+
|  1 | CentOS      | e7186252-53fc-11f0-a953-1e0029000433 |        1 |        4 | NULL    | NULL                |
|  2 | Debian      | e718b6bb-53fc-11f0-a953-1e0029000433 |        1 |        2 | NULL    | NULL                |
|  3 | Oracle      | e7191940-53fc-11f0-a953-1e0029000433 |        1 |        7 | NULL    | NULL                |
|  4 | RedHat      | e7196099-53fc-11f0-a953-1e0029000433 |        1 |        8 | NULL    | NULL                |
|  5 | SUSE        | e719d809-53fc-11f0-a953-1e0029000433 |        1 |        9 | NULL    | NULL                |
|  6 | Windows     | e71a1dfa-53fc-11f0-a953-1e0029000433 |        1 |       10 | NULL    | NULL                |
|  7 | Other       | e71a6388-53fc-11f0-a953-1e0029000433 |        1 |       11 | NULL    | NULL                |
|  8 | Novel       | e71ab196-53fc-11f0-a953-1e0029000433 |        1 |        0 | NULL    | 2025-08-22 15:22:32 |
|  9 | Unix        | e71af971-53fc-11f0-a953-1e0029000433 |        1 |        0 | NULL    | 2025-08-22 15:22:32 |
| 10 | Ubuntu      | e71b4a7c-53fc-11f0-a953-1e0029000433 |        1 |        1 | NULL    | NULL                |
| 11 | None        | e71ba2b9-53fc-11f0-a953-1e0029000433 |        1 |        0 | NULL    | 2025-08-22 15:22:32 |
| 12 | Fedora      | d2beae8d-7f6b-11f0-a953-1e0029000433 |        1 |        3 | NULL    | NULL                |
| 13 | Rocky Linux | d2bf79c0-7f6b-11f0-a953-1e0029000433 |        1 |        5 | NULL    | NULL                |
| 14 | AlmaLinux   | d2bfdf82-7f6b-11f0-a953-1e0029000433 |        1 |        6 | NULL    | NULL                |
+----+-------------+--------------------------------------+----------+----------+---------+---------------------+
14 rows in set (0.01 sec)