Skip to content

Commit 317b312

Browse files
apinnickapinnick
authored
Merge pull request #54036 from apinnick/CNV-20256-memory-dump
CNV-20256: VM memory dump
2 parents 0ff9744 + a90f60a commit 317b312

File tree

2 files changed

+167
-32
lines changed

2 files changed

+167
-32
lines changed

‎modules/virt-virtctl-commands.adoc

Lines changed: 164 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
//
33
// * virt/virt-using-the-cli-tools.adoc
44

5+
:_content-type: REFERENCE
56
[id="virt-virtctl-commands_{context}"]
6-
= Virtctl client commands
7+
= Virtctl commands
78

8-
The `virtctl` client is a command-line utility for managing {VirtProductName}
9-
resources.
9+
The `virtctl` client is a command-line utility for managing {VirtProductName} resources.
1010

1111
To view a list of `virtctl` commands, run the following command:
1212

@@ -29,71 +29,203 @@ To view a list of global command options that you can use with any `virtctl` com
2929
$ virtctl options
3030
----
3131

32-
The following table contains the `virtctl` commands used throughout the {VirtProductName} documentation.
32+
// apinnick: I recommend not breaking these commands into separate modules because of maintenance issues.
33+
// These sections would never be used independently.
3334

34-
.`virtctl` client commands
35+
[id='vm-management-commands_{context}']
36+
== Virtual machine management commands
3537

36-
[width="100%",cols="42%,58%",options="header",]
38+
You can use `virtctl` to manage virtual machine (VM) or virtual machine instance (VMI) states and to migrate a VM.
39+
40+
.VM management commands
41+
[width="100%",cols="1a,2a",options="header"]
3742
|===
3843
|Command |Description
3944

4045
|`virtctl start <vm_name>`
41-
|Start a virtual machine.
46+
|Start a VM.
4247

4348
|`virtctl start --paused <vm_name>`
44-
|Start a virtual machine in a paused state. This option enables you to interrupt the boot process from the VNC console.
49+
|Start a VM in a paused state. This option enables you to interrupt the boot process from the VNC console.
4550

4651
|`virtctl stop <vm_name>`
47-
|Stop a virtual machine.
52+
|Stop a VM.
4853

4954
|`virtctl stop <vm_name> --grace-period 0 --force`
50-
|Force stop a virtual machine. This option might cause data inconsistency or data loss.
55+
|Force stop a VM. This option might cause data inconsistency or data loss.
5156

52-
|`virtctl pause vm\|vmi <object_name>`
53-
|Pause a virtual machine or virtual machine instance. The machine state is kept
57+
|`virtctl pause vm\|vmi <vm_name>`
58+
|Pause a VM or VMI. The machine state is kept
5459
in memory.
5560

56-
|`virtctl unpause vm\|vmi <object_name>`
57-
|Unpause a virtual machine or virtual machine instance.
61+
|`virtctl unpause vm\|vmi <vm_name>`
62+
|Unpause a VM or VMI.
5863

5964
|`virtctl migrate <vm_name>`
60-
|Migrate a virtual machine.
65+
|Migrate a VM.
6166

6267
|`virtctl restart <vm_name>`
63-
|Restart a virtual machine.
68+
|Restart a VM.
69+
|===
6470

65-
|`virtctl expose <vm_name>`
66-
|Create a service that forwards a designated port
67-
of a virtual machine or virtual machine instance and expose the service on
68-
the specified port of the node.
71+
[id='vm-and-vmi-connection-commands_{context}']
72+
== VM and VMI connection commands
73+
74+
You can use `virtctl` to connect to the serial console, expose a port, set a proxy connection, specify a port, and open a VNC connection to a VM.
75+
76+
.`virtctl console`, `expose`, and `vnc` commands
77+
[width="100%",cols="1a,2a",options="header"]
78+
|===
79+
|Command |Description
6980

7081
|`virtctl console <vmi_name>`
71-
|Connect to a serial console of a virtual machine instance.
82+
|Connect to the serial console of a VMI.
83+
84+
|`virtctl expose <vm_name>`
85+
|Create a service that forwards a designated port of a VM or VMI and expose the service on the specified port of the node.
7286

7387
|`virtctl vnc --kubeconfig=$KUBECONFIG <vmi_name>`
74-
|Open a VNC (Virtual Network Client) connection to a virtual machine instance. Access the graphical console of a virtual machine instance through a VNC which requires a remote viewer on your local machine.
88+
|Open a Virtual Network Client (VNC) connection to a VMI.
89+
90+
Accessing the graphical console of a VMI through VNC requires a remote viewer on your local machine.
91+
92+
|`virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vmi_name>`
93+
|Display the port number and connect manually to a VMI by using any viewer through the VNC connection.
94+
95+
|`virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vmi_name>`
96+
|Specify a port number to run the proxy on the specified port, if that port is available.
7597

76-
|`virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vmi-name>`
77-
|Display the port number and connect manually to the virtual machine instance by using any viewer through the VNC connection.
98+
If a port number is not specified, the proxy runs on a random port.
99+
|===
100+
101+
[id='vm-volume-export-commands_{context}']
102+
== VM volume export commands
78103

79-
|`virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vmi-name>`
80-
|Specify a port number to run the proxy on the specified port, if that port is available. If a port number is not specified, the proxy runs on a random port.
104+
You can use `virtctl vmexport` commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC).
81105

106+
.`virtctl vmexport` commands
107+
[width="100%",cols="1a,2a",options="header"]
108+
|===
109+
|Command |Description
110+
111+
|`virtctl vmexport create <vmexport_name> --vm\|snapshot\|pvc=<object_name>`
112+
|Create a `VirtualMachineExport` custom resource (CR) to export a volume from a VM, VM snapshot, or PVC.
113+
114+
* `--vm`: Exports the PVCs of a VM.
115+
* `--snapshot`: Exports the PVCs contained in a `VirtualMachineSnapshot` CR.
116+
* `--pvc`: Exports a PVC.
117+
* Optional: `--ttl=1h` specifies the time to live. The default duration is 2 hours.
118+
119+
|`virtctl vmexport delete <vmexport_name>`
120+
|Delete a `VirtualMachineExport` CR manually.
121+
122+
|`virtctl vmexport download <vmexport_name> --output=<output_file> --volume=<volume_name>`
123+
|Download the volume defined in a `VirtualMachineExport` CR.
124+
125+
* `--output` specifies the file format. Example: `disk.img.gz`.
126+
* `--volume` specifies the volume to download. This flag is optional if only one volume is available.
127+
128+
Optional:
129+
130+
* `--keep-vme` retains the `VirtualMachineExport` CR after download. The default behavior is to delete the `VirtualMachineExport` CR after download.
131+
* `--insecure` enables an insecure HTTP connection.
132+
133+
|`virtctl vmexport download <vmexport_name> --<vm\|snapshot\|pvc>=<object_name> --output=<output_file> --volume=<volume_name>`
134+
|Create a `VirtualMachineExport` CR and then download the volume defined in the CR.
135+
|===
136+
137+
[id='vm-memory-dump-commands_{context}']
138+
== VM memory dump commands
139+
140+
You can use the `virtctl memory-dump` command to output a virtual machine (VM) memory dump on a PVC. You can specify an existing PVC or use the `--create-claim` flag to create a new PVC.
141+
142+
.Prerequisites
143+
144+
* The PVC volume mode must be `FileSystem`.
145+
* The PVC must be large enough to contain the memory dump.
146+
+
147+
The formula for calculating the PVC size is `(VMMemorySize + 100Mi) * FileSystemOverhead`, where `100Mi` is the memory dump overhead.
148+
149+
* You must enable the hot plug feature gate in the `HyperConverged` custom resource by running the following command:
150+
+
151+
[source,terminal]
152+
----
153+
$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
154+
--type json -p '[{"op": "add", "path": "/spec/featureGates", \
155+
"value": "HotplugVolumes"}]'
156+
----
157+
158+
.Downloading the memory dump
159+
160+
You must use the `virtctl vmexport download` command to download the memory dump:
161+
162+
[source,terminal]
163+
----
164+
$ virtctl vmexport download <vmexport_name> --vm\|pvc=<object_name> \
165+
--volume=<volume_name> --output=<output_file>
166+
----
167+
168+
.`virtctl memory-dump` commands
169+
[width="100%",cols="1a,2a",options="header"]
170+
|===
171+
|Command |Description
172+
|`virtctl memory-dump get <vm_name> --claim-name=<pvc_name>`
173+
|Save the memory dump of a VM on a PVC. The memory dump status is displayed in the `status` section of the `VirtualMachine` resource.
174+
175+
Optional:
176+
177+
* `--create-claim` creates a new PVC with the appropriate size. This flag has the following options:
178+
179+
** `--storage-class=<storage_class>`: Specify a storage class for the PVC.
180+
** `--access-mode=<access_mode>`: Specify `ReadWriteOnce` or `ReadWriteMany`.
181+
182+
|`virtctl memory-dump get <vm_name>`
183+
|Rerun the `virtctl memory-dump` command with the same PVC.
184+
185+
This command overwrites the previous memory dump.
186+
187+
|`virtctl memory-dump remove <vm_name>`
188+
|Remove a memory dump.
189+
190+
You must remove a memory dump manually if you want to change the target PVC.
191+
192+
This command removes the association between the VM and the PVC, so that the memory dump is not displayed in the `status` section of the `VirtualMachine` resource. The PVC is not affected.
193+
|===
194+
195+
[id='image-upload-commands_{context}']
196+
== Image upload commands
197+
198+
You can use the `virtctl image-upload` commands to upload a VM image to a data volume.
199+
200+
.`virtctl image-upload` commands
201+
[width="100%",cols="1a,2a",options="header"]
202+
|===
203+
|Command |Description
82204
|`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`
83-
|Upload a virtual machine image to a data volume that already exists.
205+
|Upload a VM image to a data volume that already exists.
84206

85207
|`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`
86-
|Upload a virtual machine image to a new data volume.
208+
|Upload a VM image to a new data volume of a specified requested size.
209+
|===
210+
211+
[id='environment-information-commands_{context}']
212+
== Environment information commands
87213

214+
You can use `virtctl` to view information about versions, file systems, guest operating systems, and logged-in users.
215+
216+
.`virtctl` environment information commands
217+
[width="100%",cols="1a,2a",options="header"]
218+
|===
219+
|Command |Description
88220
|`virtctl version`
89-
|Display the client and server version information.
221+
|View the `virtctl` client and server versions.
90222

91223
|`virtctl fslist <vmi_name>`
92-
|Return a full list of file systems available on the guest machine.
224+
|View the file systems available on a guest machine.
93225

94226
|`virtctl guestosinfo <vmi_name>`
95-
|Return guest agent information about the operating system.
227+
|View information about the operating systems on a guest machine.
96228

97229
|`virtctl userlist <vmi_name>`
98-
|Return a full list of logged-in users on the guest machine.
230+
|View the logged-in users on a guest machine.
99231
|===

‎virt/virt-using-the-cli-tools.adoc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
= Using the CLI tools
44
include::_attributes/common-attributes.adoc[]
55
:context: virt-using-the-cli-tools
6+
:toclevels: 3
67

78
toc::[]
89

@@ -21,7 +22,9 @@ For more comprehensive information on `oc` client commands, see the
2122
xref:../cli_reference/openshift_cli/developer-cli-commands.adoc#cli-developer-commands[{product-title} CLI tools] documentation.
2223

2324
include::modules/virt-virtctl-commands.adoc[leveloffset=+1]
25+
2426
include::modules/virt-creating-pvc-with-virtctl-guestfs.adoc[leveloffset=+1]
27+
2528
include::modules/virt-about-libguestfs-tools-virtctl-guestfs.adoc[leveloffset=+1]
2629

2730
[id="additional-resources_virt-using-the-cli-tools"]

0 commit comments

Comments
 (0)