Document KVM VM metadata handling in unmanage process by pavanaravapalli · Pull Request #595 · apache/cloudstack-documentation · GitHub

Added a warning about KVM VM metadata preservation when unmanaged.

From the enhancement PR apache/cloudstack#11061, as per discussion concluded to explicitly call out the VM behavior for unmanaged KVM VMs regarding the retention of libvirt metadata.

This PR adds a note to the documentation warning users that CloudStack does not cleanup the libvirt metadata for unamanged VMs, leaving it for user's choice.

📚 Documentation preview 📚: https://cloudstack-documentation--595.org.readthedocs.build/en/595/

Added a warning about KVM VM metadata preservation when unmanaged.

Correct me if I'm wrong, I think it may be phrased a bit shorter:

When a KVM VM is unmanaged, its metadata in the libvirt domain XML remains unchanged.
This information is left for the user’s discretion allowing them to either retain it or remove it themselves.

I specifically omitted the 4.22 version because the documentation is also versioned if I am not mistaken. So the older documentation versions will not contain this line.

Correct me if I'm wrong, I think it may be phrased a bit shorter:
When a KVM VM is unmanaged, its metadata in the libvirt domain XML remains unchanged.
This information is left for the user’s discretion allowing them to either retain it or remove it themselves.
I specifically omitted the 4.22 version because the documentation is also versioned if I am not mistaken. So the older documentation versions will not contain this line.

@phsm

It's marked for 4.22.0 milestone Last time when i checked this PR apache/cloudstack#11061. How ever this Doc PR goes to main branch.

@pavanaravapalli @phsm, I think it does not hurt to leave the version in as a lot of people will read the “latest” documentation without caring to select a specific version.

If otherwise fine, I’m merging.

Sorry, mistakently approved this. @pavanaravapalli can you please check my comment.

This information is already document in this PR https://github.com/apache/cloudstack-documentation/pull/562/files

is this something else ?

@harikrishna-patnala

This is different from https://github.com/apache/cloudstack-documentation/pull/562/files.
It focuses on retaining CloudStack metadata on libvirt XML even after the VM resource is unmanaged from ACS.

Correct me if I'm wrong, I think it may be phrased a bit shorter:
When a KVM VM is unmanaged, its metadata in the libvirt domain XML remains unchanged.
This information is left for the user’s discretion allowing them to either retain it or remove it themselves.
I specifically omitted the 4.22 version because the documentation is also versioned if I am not mistaken. So the older documentation versions will not contain this line.
@phsm

It's marked for 4.22.0 milestone Last time when i checked this PR apache/cloudstack#11061. How ever this Doc PR goes to main branch.

@pavanaravapalli @phsm the PR apache/cloudstack#11061 is merged after 4.22.0 release (earlier it was part of 4.22.0 milestone, but not merged before the release), so the doc PR should target 4.22 (as this should go with 4.22.1 release notes later, and also merged forward to main). cc @DaanHoogland

Correct me if I'm wrong, I think it may be phrased a bit shorter:
When a KVM VM is unmanaged, its metadata in the libvirt domain XML remains unchanged.
This information is left for the user’s discretion allowing them to either retain it or remove it themselves.
I specifically omitted the 4.22 version because the documentation is also versioned if I am not mistaken. So the older documentation versions will not contain this line.
@phsm
It's marked for 4.22.0 milestone Last time when i checked this PR apache/cloudstack#11061. How ever this Doc PR goes to main branch.
@pavanaravapalli @phsm the PR apache/cloudstack#11061 is merged after 4.22.0 release (earlier it was part of 4.22.0 milestone, but not merged before the release), so the doc PR should target 4.22 (as this should go with 4.22.1 release notes later, and also merged forward to main). cc @DaanHoogland

@sureshanaparti
Should I update the version in the docs from 4.22.0 → 4.22.1?
Will this get merged into both main and 4.22.1, or do I need to open separate PRs?

@sureshanaparti Should I update the version in the docs from 4.22.0 → 4.22.1? Will this get merged into both main and 4.22.1, or do I need to open separate PRs?

@pavanaravapalli correct, version should be 4.22.1. no need of separate PR.

Suggested change

      
               Starting with the 4.22.0 release, when a KVM VM is unmanaged, its infrastructure metadata (zone, pod, cluster, and host) in the libvirt VM XML is preserved.
          
               Starting with the 4.22.1 release, when a KVM instance is unmanaged, the infrastructure metadata (zone, pod, cluster, and host details) is preserved in the libvirt VM XML.

Note: if any change in the retaining behavior, mainly clearing the metadata while unmanaging instance is handled before 4.22.1, this warning message is not needed and has to be reverted. cc @DaanHoogland

@sureshanaparti
Suresh, prior to 4.22.1, the preserved libvirt XML behavior was meant to support non-transient domains required for unmanaged VMs. During that process, no CloudStack metadata was stored — it only started being preserved after the libvirt metadata enhancement. I think this is worth mentioning in the release notes. Please correct me if I’m mistaken.

@sureshanaparti
Changes applied as suggested — ready for review.

@sureshanaparti Suresh, prior to 4.22.1, the preserved libvirt XML behavior was meant to support non-transient domains required for unmanaged VMs. During that process, no CloudStack metadata was stored — it only started being preserved after the libvirt metadata enhancement. I think this is worth mentioning in the release notes. Please correct me if I’m mistaken.

fine, we can mention that. I'm making a point that if any PR addresses the cleanup of the libvirt metadata in 4.22.1 itself, this note in the doc has to revisited.

@blueorangutan docbuild

@sureshanaparti a Jenkins job has been kicked to build the document. I'll keep you posted as I make progress.

Verified the doc here: https://cloudstack-documentation--595.org.readthedocs.build/en/595/adminguide/virtual_machines/importing_unmanaging_vms.html

Document KVM VM metadata handling in unmanage process

4c1844c

Added a warning about KVM VM metadata preservation when unmanaged.

pavanaravapalli mentioned this pull request Nov 10, 2025

enhancement: add instance info as Libvirt metadata apache/cloudstack#11061

Merged

2 of 14 tasks

DaanHoogland changed the base branch from main to 4.22 November 11, 2025 08:02

DaanHoogland added this to the 4.22.0 milestone Nov 11, 2025

DaanHoogland approved these changes Nov 11, 2025

View reviewed changes

harikrishna-patnala approved these changes Nov 11, 2025

View reviewed changes

harikrishna-patnala self-requested a review November 11, 2025 08:29

weizhouapache modified the milestones: 4.22.0, 4.22.1 Nov 11, 2025

sureshanaparti reviewed Nov 12, 2025

View reviewed changes

Update warning for KVM instance unmanaged metadata

4a596e4

sureshanaparti added this to Apache CloudStack 4.22.1 Jan 7, 2026

sureshanaparti moved this to In Progress in Apache CloudStack 4.22.1 Jan 7, 2026

sureshanaparti approved these changes May 19, 2026

View reviewed changes

sureshanaparti merged commit b258a08 into apache:4.22 May 19, 2026
1 check passed

github-project-automation Bot moved this from In Progress to Done in Apache CloudStack 4.22.1 May 19, 2026

               - The Instance must be a VMware Instance (as of CloudStack 4.19, it's also possible to unmanage a KVM-based Instances)
+              .. warning::
+                 Starting with the 4.22.0 release, when a KVM VM is unmanaged, its infrastructure metadata (zone, pod, cluster, and host) in the libvirt VM XML is preserved.

	Starting with the 4.22.0 release, when a KVM VM is unmanaged, its infrastructure metadata (zone, pod, cluster, and host) in the libvirt VM XML is preserved.
	Starting with the 4.22.1 release, when a KVM instance is unmanaged, the infrastructure metadata (zone, pod, cluster, and host details) is preserved in the libvirt VM XML.

Document KVM VM metadata handling in unmanage process by pavanaravapalli · Pull Request #595 · apache/cloudstack-documentation · GitHub

Repository navigation

Document KVM VM metadata handling in unmanage process - #595

Document KVM VM metadata handling in unmanage process#595sureshanaparti merged 2 commits intoapache:4.22apache/cloudstack-documentation:4.22from pavanaravapalli:patch-1pavanaravapalli/cloudstack-documentation:patch-1Copy head branch name to clipboard

Conversation

pavanaravapalli commented Nov 10, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phsm commented Nov 10, 2025

Uh oh!

pavanaravapalli commented Nov 11, 2025

Uh oh!

DaanHoogland commented Nov 11, 2025

Uh oh!

harikrishna-patnala left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

harikrishna-patnala Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

pavanaravapalli Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sureshanaparti commented Nov 11, 2025

Uh oh!

pavanaravapalli commented Nov 11, 2025

Uh oh!

sureshanaparti commented Nov 12, 2025

Uh oh!

sureshanaparti Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pavanaravapalli Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

pavanaravapalli Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

sureshanaparti Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

sureshanaparti commented May 18, 2026

Uh oh!

blueorangutan commented May 18, 2026

Uh oh!

sureshanaparti commented May 19, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Document KVM VM metadata handling in unmanage process#595
sureshanaparti merged 2 commits into
apache:4.22from
pavanaravapalli:patch-1

pavanaravapalli commented Nov 10, 2025 •
edited by github-actions Bot
Loading

harikrishna-patnala left a comment •
edited
Loading

pavanaravapalli Nov 11, 2025 •
edited
Loading

sureshanaparti Nov 12, 2025 •
edited
Loading