Skip to content

Commit 73b0694

Browse files
palnabarunpalnabarun
committed
📖 Document VirtualMachineSnapshot concept
Adds documentation for the VirtualMachineSnapshot concept including usage, examples, and troubleshooting tips. Signed-off-by: Nabarun Pal <nabarun.pal@broadcom.com>
1 parent 66c7b2a commit 73b0694

File tree

3 files changed

+190
-1
lines changed

3 files changed

+190
-1
lines changed

‎docs/concepts/workloads/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ This section provides information about workload resources, such as:
1212
* [`VirtualMachine` controller](./vm-controller.md)
1313
* [`VirualMachineClass`](./vm-class.md)
1414
* [`VirtualMachineGroup`](./vm-group.md)
15+
* [`VirtualMachineSnapshot`](./vm-snapshot.md)
1516
* [`WebConsoleRequest`](./vm-web-console.md)
1617

1718
In addition to the workload resources themselves, there is documentation related to broader topics related to workloads:

‎docs/concepts/workloads/vm-snapshot.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# VirtualMachineSnapshot
2+
3+
VirtualMachineSnapshot resources enable consumers to take Snapshot of their VirtualMachines. It leverages the providers Snapshot capabilities to create VM snapshots.
4+
5+
## Overview
6+
7+
A VirtualMachineSnapshots is a namespace-scoped Kubernetes resource that:
8+
9+
- Creates snapshots in the provider for the referred VM
10+
- Supports taking a snapshot with or without memory
11+
- Supports quiescing the guest when creating a snapshot
12+
13+
## Creating a VirtualMachineSnapshot
14+
15+
### Snapshot without memory
16+
17+
A snapshot which doesn't include VM memory:
18+
19+
```yaml
20+
apiVersion: vmoperator.vmware.com/v1alpha5
21+
kind: VirtualMachineSnapshot
22+
metadata:
23+
name: snap-1
24+
spec:
25+
description: "Snapshot of my-vm without memory"
26+
vmName: my-vm
27+
```
28+
29+
### Snapshot with memory
30+
31+
A snapshot which includes VM memory:
32+
33+
```yaml
34+
apiVersion: vmoperator.vmware.com/v1alpha5
35+
kind: VirtualMachineSnapshot
36+
metadata:
37+
name: snap-2
38+
spec:
39+
description: "Snapshot of my-vm with memory"
40+
vmName: my-vm
41+
memory: true
42+
```
43+
44+
### Snapshot while queiscing
45+
46+
A snapshot which specifies a Quiesce timeout:
47+
48+
```yaml
49+
apiVersion: vmoperator.vmware.com/v1alpha5
50+
kind: VirtualMachineSnapshot
51+
metadata:
52+
name: snap-3
53+
spec:
54+
description: "Snapshot of my-vm with a consistent state of the guest filesystem"
55+
vmName: my-vm
56+
memory: true
57+
queisce:
58+
timeout: 10min
59+
```
60+
61+
> Note: VMware Tools must be installed on the Guest OS.
62+
63+
## Reverting to a snapshot
64+
65+
Set the `spec.currentSnapshotName` on the VM to revert to a snapshot:
66+
67+
```yaml
68+
apiVersion: vmoperator.vmware.com/v1alpha5
69+
kind: VirtualMachine
70+
metadata:
71+
name: my-vm
72+
spec:
73+
currentSnapshotName: snap-1
74+
```
75+
76+
Once the VM is reverted, `status.currentSnapshot` should refer to the snapshot set in `spec.currentSnapshotName` and `spec.currentSnapshotName` would be removed if the VM was succesfully reverted.
77+
78+
```yaml
79+
status:
80+
currentSnapshot:
81+
type: Managed
82+
name: snap-1
83+
```
84+
85+
Please refer to the [Troubleshooting](#troubleshooting) section below if the operation fails.
86+
87+
## Status and Conditions
88+
89+
### Status
90+
91+
#### VirtualMachineSnapshot
92+
93+
```yaml
94+
status:
95+
conditions:
96+
- lastTransitionTime: "2025-10-27T14:55:26Z"
97+
message: ""
98+
reason: "True"
99+
status: "True"
100+
type: VirtualMachineSnapshotCSISynced
101+
- lastTransitionTime: "2025-10-27T14:55:26Z"
102+
message: ""
103+
reason: "True"
104+
status: "True"
105+
type: VirtualMachineSnapshotCreated
106+
- lastTransitionTime: "2025-10-27T14:55:26Z"
107+
message: ""
108+
reason: "True"
109+
status: "True"
110+
type: VirtualMachineSnapshotReady
111+
powerState: PoweredOn
112+
storage:
113+
requested:
114+
- storageClass: wcpglobal-storage-profile
115+
total: 25Gi
116+
used: "12226581330"
117+
uniqueID: snapshot-226
118+
```
119+
120+
#### VirtualMachine
121+
122+
```yaml
123+
status:
124+
...
125+
currentSnapshot:
126+
name: snap-2
127+
type: Managed
128+
...
129+
rootSnapshots:
130+
- name: snap-1
131+
type: Managed
132+
...
133+
```
134+
135+
### Conditions
136+
137+
#### VirtualMachineSnapshot
138+
139+
| Condition | Description |
140+
| --------------------------------- | ----------------------------------------- |
141+
| `VirtualMachineSnapshotCSISynced` | CSI volume has been synced |
142+
| `VirtualMachineSnapshotCreated` | Snapshot has been created on the provider |
143+
| `VirtualMachineSnapshotReady` | Snapshot has been succesfully reconciled |
144+
145+
#### VirtualMachine
146+
147+
| Condition | Description |
148+
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
149+
| `VirtualMachineSnapshotRevertSucceeded` | Snapshot is succesfully reverted. This condition can be seen only when the snapshot revert operation fails for some reason. Steady state is for the condition to not exist. |
150+
151+
### Unmanaged Snapshots
152+
153+
Snapshots directly created via the provider can't be managed through VM Operator.
154+
Those snapshots will be marked as `Unamanaged` in VM's `status.currentSnapshot`
155+
and `status.rootSnapshots`.
156+
157+
## Best Practices
158+
159+
### Design Considerations
160+
161+
1. **Meaningful Names**: Use descriptive names that indicate the purpose of the snapshot
162+
2. **Use Description**: Use the description field to add more context
163+
3. **Number of snapshots**: Prefer limiting the number of snapshots to less than 32
164+
4. **Unmanaged Snapshots**: Avoid creating unmanaged snapshots directly on the provider
165+
166+
### Troubleshooting
167+
168+
Common issues and solutions:
169+
170+
| Issue | Cause | Solution |
171+
| ------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- |
172+
| Snapshot doesn't include memory | Missing `spec.memory` | Set VM Snapshot's `spec.memory` field to `true` |
173+
| VM reverts to a PoweredOff mode | Snapshot taken without memory | Set VM Snapshot's `spec.memory` field to `true` |
174+
| Snapshot create failed | Might be a VKS node | VKS nodes can't be snapshotted or reverted |
175+
| VM not reverting | Might be a VKS node | VKS nodes can't be snapshotted or reverted |
176+
| Snapshot revert failed | CSI Snapshot exists for a volume | Delete any CSI volume snapshot which exists between current state and the snapshot being reverted to |
177+
178+
179+
## API Reference
180+
181+
For detailed API specifications, see:
182+
183+
- VirtualMachineSnapshot CRD documentation
184+
- VirtualMachine `spec.currentSnapshotName`, `status.currentSnapshot` and `status.rootSnapshots` field documentation
185+
186+
## Related Resources
187+
188+
- [VirtualMachine](./vm.md) - Core VM resource documentation

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ nav:
139139
- Guest Customization: concepts/workloads/guest.md
140140
- VirtualMachine Placement: concepts/workloads/vm-placement.md
141141
- VirtualMachineGroup: concepts/workloads/vm-group.md
142+
- VirtualMachineSnapshot: concepts/workloads/vm-snapshot.md
142143
- Images:
143144
- concepts/images/README.md
144145
- VirtualMachineImage: concepts/images/vm-image.md
@@ -181,4 +182,3 @@ nav:
181182
- Build from Source: ref/proj/build.md
182183
- Create a Release: ref/proj/release.md
183184
- Writing Documentation: ref/proj/docs.md
184-

0 commit comments

Comments
 (0)