📖 Document enhanced storage APIs and automatic volume registration #1355
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This patch ensures "mkdocs serve" live-reloads when the docs changes.
Add comprehensive documentation for the new storage controller and volume management capabilities in VirtualMachine resources. This documentation covers features that were previously undocumented, making it difficult for users to understand and utilize the advanced storage configuration options. The documentation includes: - Controller types (IDE, NVME, SATA, SCSI) with their capabilities, limits, and SCSI adapter type variations - Controller sharing modes (None, Physical, Virtual) for specialized workloads like Microsoft WSFC and clustering scenarios - Explicit controller configuration in spec.hardware section - Volume specification fields including placement control via controllerType, controllerBusNumber, and unitNumber - Disk modes (Persistent, IndependentPersistent, NonPersistent, IndependentNonPersistent) with their snapshot behavior - Sharing modes for multi-writer scenarios - Application-specific configurations for OracleRAC and MicrosoftWSFC workloads with automatic defaults - Volume placement logic for automatic and explicit controller assignment - Enhanced status reporting showing controller topology and volume placement details
Add comprehensive documentation for the automatic disk registration feature that converts classic disks from VM images into PVC-backed managed volumes. This functionality was previously undocumented, making it difficult for users to understand storage lifecycle management, troubleshoot registration issues, or customize disk configurations. The documentation covers: - Schema upgrade process that backfills unmanaged disks into spec.volumes with controller placement information - Automatic PVC creation workflow including CnsRegisterVolume mechanism for in-place disk registration without data movement - Mapping spec.volumes entries to image disks using controllerType, controllerBusNumber, and unitNumber for explicit PVC control - Linked clone promotion behavior for VMs deployed from templates - Differences between OVF and VM image types during conversion - Managing automatically created PVCs including ownership, storage class inheritance, and lifecycle - CNS volume registration technical details with workflow phases, status tracking, and CnsRegisterVolume custom resource usage - Volume removal procedures distinguishing between user-added and image-based volumes with data preservation guidelines - Troubleshooting guidance for registration failures with specific conditions, commands, and common issues This enables platform administrators and developers to: 1. Understand how image disks are automatically converted to PVCs 2. Customize PVC assignments by pre-populating spec.volumes 3. Monitor registration progress via status conditions 4. Troubleshoot registration failures using CnsRegisterVolume resources 5. Manage storage lifecycle for VM disks through Kubernetes APIs 6. Control storage classes and disk placement for image-based volumes
Add comprehensive documentation explaining how VM Operator automatically upgrades VirtualMachine resources to match the current schema version and activated features. This process was previously undocumented, making it difficult for users to understand why their VMs were being modified during reconciliation or how to verify upgrade completion. The documentation covers: - Upgrade tracking using three annotations: build version, schema version, and feature version bitmask - Feature version bits (Base, VMSharedDisks, AllDisksArePVCs) and how they compose into the overall feature version - Upgrade process stages: base UUID reconciliation, volume backfill, controller reconciliation, and device placement reconciliation - Volume backfill process that adds classic disks to spec.volumes with controller placement information - Controller reconciliation that populates spec.hardware with IDE, NVME, SATA, and SCSI controllers from vSphere - Device reconciliation using CnsNodeVmAttachment to map PVCs to disk UUIDs for placement backfill - Mutation webhook behavior for setting volume and controller defaults based on applicationType and upgrade status - Validation webhook enforcement of placement and application-specific constraints after upgrade - Complete upgrade lifecycle example showing progression through feature versions This enables users to: 1. Understand why VMs are modified during reconciliation 2. Track upgrade progress using annotations and feature versions 3. Verify when a VM is fully upgraded and ready for new features 4. Predict webhook behavior based on upgrade state 5. Debug upgrade issues by checking feature version bits
Minimum allowed line rate is |
aruneshpa
approved these changes
Dec 1, 2025
Collaborator
aruneshpa
left a comment
aruneshpa
left a comment
There was a problem hiding this comment.
Overall, this looks mega. It is helpful to see all these volume and controller constraints in plain English and will definitely help users.
A few minor points that I noted down when reviewing:
- Mixed use of the work "classic" and "unmanaged" for volumes. Do you think it is worthwhile to make these consistent? For the most part, "classic" is used for disks and "unmanaged" is used for volumes. But I still think it might be a good idea to consolidate to "unmanaged disk".
- Sharing Mode: Since controllers and volumes both have sharing modes, it can be confusing to figure out which one we are referring to. Your doc heading indentation is organized well, but the reader has to look at their heading structure to figure out which sharing mode we are referring to. Maybe prefix "controller" or "volume" everywhere sharing mode is referenced?
| 3. **Automatic Registration**: During the first reconciliation after deployment, the system: | ||
| - Detects any unmanaged (non-PVC) disks attached to the VM | ||
| - Creates a PVC for each disk with appropriate metadata | ||
| - Registers the existing disk with the CNS storage provider |
Collaborator
There was a problem hiding this comment.
Should we call out that we wait for the volume to be bound? You do that elsewhere in the docs.
| - Creates a PVC for each disk with appropriate metadata | ||
| - Registers the existing disk with the CNS storage provider | ||
| - Updates `spec.volumes` to reference the newly created PVC | ||
|
|
Collaborator
There was a problem hiding this comment.
Also, do we care enough to explain that this type of volume is a "static" volume and how it is different from a dynamic volume?
| !!! tip "Pre-mapping Image Disks" | ||
| To control the PVC names or storage classes for image disks, create `spec.volumes` entries before deploying the VM with `controllerType`, `controllerBusNumber`, and `unitNumber` values matching the disks in the image's `status.disks`. See [Mapping spec.volumes to Image Disks](#mapping-specvolumes-to-image-disks) for details. | ||
|
|
||
| ##### Linked Clone Promotion |
Collaborator
There was a problem hiding this comment.
I think this section (or at least most of the content) is duplicated?
|
|
||
| 2. **Automatic generation if not specified**: If you don't pre-populate `spec.volumes` for image disks, VM Operator automatically creates entries during the backfill process. | ||
|
|
||
| 3. **PVC reference is optional**: You can provide a `persistentVolumeClaim.claimName` to use a specific PVC for the image disk. If omitted, a PVC will be automatically created with a generated name. |
Collaborator
There was a problem hiding this comment.
Just wondering. If a user specifies a PVC that already exists and does not have DataSourceRef but is an actual, dynamic volume -- what happens? Do we need to call that out here?
Collaborator
Author
There was a problem hiding this comment.
We will actually apply the DS ref.
bryanv
approved these changes
Dec 3, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does this PR do, and why is it needed?
This patch includes:
Live-reload when mkdocs serve - Improves documentation development workflow by enabling automatic reloading when documentation files change during local preview.
Document enhanced storage controller and volume APIs - Adds detailed documentation for storage controller and volume management features:
Document automatic PVC creation for VM image disks - Adds comprehensive coverage of automatic disk registration:
Document schema upgrade -- Adds documentation for VM schema upgrade.
Which issue(s) is/are addressed by this PR? (optional, in
fixes #<issue number>(, fixes #<issue_number>, ...)format, will close the issue(s) when PR gets merged):Fixes
NAAre there any special notes for your reviewer:
Please add a release note if necessary:
📚 Documentation preview 📚: https://vm-operator--1355.org.readthedocs.build/en/1355/