compute: add PCI topology and hotplug port reservation docs by mhenriks · Pull Request #980 · kubevirt/user-guide

mhenriks · 2026-03-18T00:09:20Z

Document the PCI topology versions (v1, v2, v3), how hotplug port reservation works, and upgrade behavior. Includes troubleshooting guidance for Windows VMs with offline disks after upgrading from KubeVirt 1.6/1.7 to versions with the v3 fix (1.6.4, 1.7.2, 1.8+).

What this PR does / why we need it:

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #

Special notes for your reviewer:

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

Design: A design document was considered and is present (link) or not required
PR: The PR description is expressive enough and will help future contributors
Code: Write code that humans can understand and Keep it simple
Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
Upgrade: Impact of this change on upgrade flows was considered and addressed if required
Testing: New code requires new unit tests. New features and bug fixes require at least on e2e test
Documentation: A user-guide update was considered and is present (link) or not required. You want a user-guide update if it's a user facing feature / API change.
Community: Announcement to kubevirt-dev was considered

Release note:

compute: add PCI topology and hotplug port reservation docs

mhenriks · 2026-03-18T00:10:36Z

cc @jean-edouard @vladikr @xpivarc

kubevirt-bot · 2026-05-07T18:44:35Z

There has been no activity on this PR for 45 days.
To protect limited CI resources, it has been automatically labelled 'stale'.
This PR will automatically rot after an additional 14 days of inactivity, and will be closed shortly after that.

What you can do:

If the PR is waiting on you to respond to a question or feedback and/or update the PR, please do so.
You can mark the PR as fresh and remove the label with the following command: /remove-lifecycle stale
If this PR is safe to close now, please help the project by closing it with: /close
If you need attention on this PR from a reviewer, you can raise it on the agenda of the relevant SIG meeting or KubeVirt Community meeting, or ping the kubevirt-dev slack channel.

/lifecycle stale

mhenriks · 2026-05-07T19:28:43Z

/remove-lifecycle stale

kubevirt-bot · 2026-06-03T16:10:49Z

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

jean-edouard

/approve

kubevirt-bot · 2026-06-08T13:59:34Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jean-edouard

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~docs/compute/OWNERS~~ [jean-edouard]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

dhiller · 2026-06-09T14:52:06Z

Removing needs-rebase label — the PR was force-pushed after the label was applied, which likely coincided with a GitHub glitch.

🤖 Assisted by Claude

aburdenthehand

Nice work @mhenriks
For the most part this is clean and clear but I think the Topology:KubeVirt versioning could be made clearer, along with a lot of the headings.

aburdenthehand · 2026-06-12T13:23:35Z

+Same hotplug capacity as v2, same device addresses as v1.
+
+## Upgrade Behavior
+


We previously said "Understanding these is important when upgrading, as VMs created under different versions may behave differently."
So let's add an introduction here that more or less repeats that and links back to the Topology–KubeVirt version table. We can also then simplify these headings so they don't need the KubeVirt versions in them. (ie ### Upgrading from v1 to v3)

Document the PCI topology versions (v1, v2, v3), how hotplug port reservation works, and upgrade behavior. Includes troubleshooting guidance for Windows VMs with offline disks after upgrading from KubeVirt 1.6/1.7 to versions with the v3 fix (1.6.4, 1.7.2, 1.8+). Signed-off-by: Michael Henriksen <mhenriks@redhat.com>

aburdenthehand

Great stuff @mhenriks.
I suggest we remove a bunch of the extraneous emphases in the upgrading sections as they take away from the headings and VM status markup.

aburdenthehand · 2026-06-29T14:43:19Z

+
+#### Stopped VMs (one-time address shift)
+
+VMs that were **stopped** during the upgrade cannot be detected as v2, since


Suggested change

VMs that were **stopped** during the upgrade cannot be detected as v2, since

VMs that were stopped during the upgrade cannot be detected as v2, since

aburdenthehand · 2026-06-29T14:43:39Z

+there is no running domain to inspect. When they next start:
+
+1. The VM gets the v3 topology (v1 placeholder formula).
+2. Device PCI addresses shift back to the v1 layout — a **one-time change**.


Suggested change

2. Device PCI addresses shift back to the v1 layout — a **one-time change**.

2. Device PCI addresses shift back to the v1 layout — this is a one-time change.

aburdenthehand · 2026-06-29T14:44:04Z

+1. The VM gets the v3 topology (v1 placeholder formula).
+2. Device PCI addresses shift back to the v1 layout — a **one-time change**.
+
+This may cause issues for **Windows VMs** that had been running with v2


Suggested change

This may cause issues for **Windows VMs** that had been running with v2

This may cause issues for Windows VMs that had been running with v2

aburdenthehand · 2026-06-29T14:44:29Z

+4. On subsequent reboots, the frozen placeholder count is used, keeping PCI
+   addresses stable.
+
+**No action is required** for these VMs. The addresses are preserved


Suggested change

**No action is required** for these VMs. The addresses are preserved

No action is required for these VMs. The addresses are preserved

kubevirt-bot added the dco-signoff: yes Indicates the PR's author has DCO signed all their commits. label Mar 18, 2026

kubevirt-bot requested review from jean-edouard and victortoso March 18, 2026 00:09

kubevirt-bot added the size/L label Mar 18, 2026

kubevirt-bot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label May 7, 2026

kubevirt-bot removed the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label May 7, 2026

kubevirt-bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 3, 2026

jean-edouard reviewed Jun 8, 2026

View reviewed changes

kubevirt-bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jun 8, 2026

mhenriks force-pushed the pci-guide branch from a648c35 to 817b8a6 Compare June 8, 2026 19:16

dhiller removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 9, 2026

aburdenthehand reviewed Jun 12, 2026

View reviewed changes

mhenriks force-pushed the pci-guide branch from 817b8a6 to a9762b4 Compare June 12, 2026 18:49

aburdenthehand reviewed Jun 29, 2026

View reviewed changes

		Same hotplug capacity as v2, same device addresses as v1.

		## Upgrade Behavior


		#### Stopped VMs (one-time address shift)

		VMs that were stopped during the upgrade cannot be detected as v2, since

	VMs that were stopped during the upgrade cannot be detected as v2, since
	VMs that were stopped during the upgrade cannot be detected as v2, since

	2. Device PCI addresses shift back to the v1 layout — a one-time change.
	2. Device PCI addresses shift back to the v1 layout — this is a one-time change.

	This may cause issues for Windows VMs that had been running with v2
	This may cause issues for Windows VMs that had been running with v2

	No action is required for these VMs. The addresses are preserved
	No action is required for these VMs. The addresses are preserved

Uh oh!

Conversation

mhenriks commented Mar 18, 2026

Uh oh!

mhenriks commented Mar 18, 2026

Uh oh!

kubevirt-bot commented May 7, 2026

Uh oh!

mhenriks commented May 7, 2026

Uh oh!

kubevirt-bot commented Jun 3, 2026

Uh oh!

jean-edouard left a comment

Choose a reason for hiding this comment

Uh oh!

kubevirt-bot commented Jun 8, 2026

Uh oh!

dhiller commented Jun 9, 2026

Uh oh!

aburdenthehand left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aburdenthehand Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aburdenthehand left a comment

Choose a reason for hiding this comment

Uh oh!

aburdenthehand Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

aburdenthehand Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

aburdenthehand Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

aburdenthehand Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants