Merge pull request #61571 from apinnick/update-virctl-commands

Update virctl commands

Author: apinnick

_topic_maps/_topic_map.yml

@@ -3644,8 +3644,6 @@ Topics:
   - Name: Installing OKD Virtualization using the CLI
     File: installing-virt-cli
     Distros: openshift-origin
-  - Name: Installing the virtctl client
-    File: virt-installing-virtctl
   - Name: Uninstalling OpenShift Virtualization
     File: uninstalling-virt
     Distros: openshift-enterprise
@@ -3660,7 +3658,7 @@ Topics:
   Distros: openshift-origin
 - Name: Security policies
   File: virt-security-policies
-- Name: Using the CLI tools
+- Name: Using the virtctl and libguestfs CLI tools
   File: virt-using-the-cli-tools
 - Name: Virtual machines
   Dir: virtual_machines

modules/virt-about-libguestfs-tools-virtctl-guestfs.adoc

@@ -2,8 +2,9 @@
 //
 // * virt/virt-using-the-cli-tools.adoc
 
+:_content-type: REFERENCE
 [id="virt-about-libguestfs-tools-virtctl-guestfs_{context}"]
-= Libguestfs tools and virtctl guestfs
+= Libguestfs and virtctl guestfs commands
 
 `Libguestfs` tools help you access and modify virtual machine (VM) disk images. You can use `libguestfs` tools to view and edit files in a guest, clone and build virtual machines, and format and resize disks.
 

modules/virt-creating-pvc-with-virtctl-guestfs.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: PROCEDURE
 [id="virt-creating-pvc-with-virtctl-guestfs_{context}"]
-= Creating a container using virtctl guestfs
+= Deploying a libguestfs-tools container by using virtctl
 
 You can use the `virtctl guestfs` command to deploy an interactive container with `libguestfs-tools` and a persistent volume claim (PVC) attached to it.
 

modules/virt-installing-virtctl-client-yum.adoc

@@ -4,16 +4,32 @@
 
 :_content-type: PROCEDURE
 [id="virt-installing-virtctl-client-yum_{context}"]
-= Installing the virtctl client using the yum utility
+= Installing virtctl on {op-system-base}
 
-Install the `virtctl` client from the `kubevirt-virtctl` package.
+You install the `virtctl` RPM on {op-system-base-full} by enabling the {VirtProductName} repository and installing the `kubevirt-virtctl` package.
 
 .Prerequisites
 
-* You enabled an {VirtProductName} repository on your {op-system-base-full} system.
+* Each host in your cluster must be registered with Red Hat Subscription Manager (RHSM) and have an active {product-title} subscription.
 
 .Procedure
 
+* Enable the appropriate {VirtProductName} repository for your operating system by using the `subscription-manager` CLI tool:
+
+** {op-system-base} 9:
++
+[source,terminal]
+----
+# subscription-manager repos --enable cnv-4.13-for-rhel-9-x86_64-rpms
+----
+
+** {op-system-base} 8:
++
+[source,terminal]
+----
+# subscription-manager repos --enable cnv-4.13-for-rhel-8-x86_64-rpms
+----
+
 * Install the `kubevirt-virtctl` package:
 +
 [source,terminal]

modules/virt-installing-virtctl-client.adoc

@@ -4,15 +4,15 @@
 
 :_content-type: PROCEDURE
 [id="virt-installing-virtctl-client_{context}"]
-= Installing the virtctl client on Linux, Windows, and macOS
+= Installing virtctl on Linux, Windows, and macOS
 
-Download and install the `virtctl` client for your operating system.
+Download and install the `virtctl` binary for your operating system.
 
 .Procedure
 
-. Navigate to *Virtualization > Overview* in the {product-title} web console.
+. Navigate to *Virtualization -> Overview* page in the {product-title} web console.
 
-. Click the *Download virtctl* link on the upper right corner of the page and download the `virtctl` client for your operating system.
+. Click the *Download virtctl* link to download the `virtctl` binary for your operating system.
 
 . Install `virtctl`:
 

modules/virt-openshift-client-commands.adoc

@@ -8,7 +8,20 @@
 
 The `virtctl` client is a command-line utility for managing {VirtProductName} resources.
 
-.`virtctl` general commands
+[NOTE]
+====
+The virtual machine (VM) commands also apply to virtual machine instances unless otherwise specified.
+====
+
+// apinnick: I recommend not breaking these sections into separate modules because of maintenance issues.
+// These sections will never be used independently.
+
+[id='virtctl-information-commands_{context}']
+== Virtctl information commands
+
+You use `virtctl` information commands to view information about the `virtctl` client.
+
+.Information commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
@@ -25,15 +38,31 @@ The `virtctl` client is a command-line utility for managing {VirtProductName} re
 |View a list of global command options for any `virtctl` command.
 |===
 
-// apinnick: I recommend not breaking these sections into separate modules because of maintenance issues.
-// These sections will never be used independently.
+[id='vm-information-commands_{context}']
+== VM information commands
+
+You can use `virtctl` to view information about VMs and VMIs.
+
+.VM information commands
+[width="100%",cols="1a,2a",options="header"]
+|===
+|Command |Description
+|`virtctl fslist <vm_name>`
+|View the file systems available on a guest machine.
+
+|`virtctl guestosinfo <vm_name>`
+|View information about the operating systems on a guest machine.
+
+|`virtctl userlist <vm_name>`
+|View the logged-in users on a guest machine.
+|===
 
 [id='vm-management-commands_{context}']
-== VM and VMI management commands
+== VM management commands
 
-You can use `virtctl` to manage virtual machine (VM) or virtual machine instance (VMI) states and to migrate a VM.
+You use `virtctl` virtual machine (VM) management commands to manage and migrate VMs and VMIs.
 
-.`virtctl` VM management commands
+.VM management commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
@@ -49,12 +78,11 @@ You can use `virtctl` to manage virtual machine (VM) or virtual machine instance
 |`virtctl stop <vm_name> --grace-period 0 --force`
 |Force stop a VM. This option might cause data inconsistency or data loss.
 
-|`virtctl pause vm\|vmi <vm_name>`
-|Pause a VM or VMI. The machine state is kept
-in memory.
+|`virtctl pause vm <vm_name>`
+|Pause a VM. The machine state is kept in memory.
 
-|`virtctl unpause vm\|vmi <vm_name>`
-|Unpause a VM or VMI.
+|`virtctl unpause vm <vm_name>`
+|Unpause a VM.
 
 |`virtctl migrate <vm_name>`
 |Migrate a VM.
@@ -63,41 +91,50 @@ in memory.
 |Restart a VM.
 |===
 
-[id='vm-and-vmi-connection-commands_{context}']
-== VM and VMI connection commands
+[id='vm-connection-commands_{context}']
+== VM connection commands
 
-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.
+You use `virtctl` connection commands to expose ports and connect to VMs and VMIs.
 
-.`virtctl console`, `expose`, and `vnc` commands
+.VM connection commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
-|`virtctl console <vmi_name>`
-|Connect to the serial console of a VMI.
+|`virtctl console <vm_name>`
+|Connect to the serial console of a VM.
 
 |`virtctl expose <vm_name>`
-|Create a service that forwards a designated port of a VM or VMI and expose the service on the specified port of the node.
+|Create a service that forwards a designated port of a VM and expose the service on the specified port of the node.
+
+|`virtctl scp -i <ssh_key> <file_name> <user_name>@<vm_name>`
+|Copy a file from your machine to a VM. This command uses the private key of an SSH key pair. The VM must be configured with the public key.
+
+|`virtctl scp -i <ssh_key> <user_name@<vm_name>:<file_name> .`
+|Copy a file from a VM to your machine. This command uses the private key of an SSH key pair. The VM must be configured with the public key.
 
-|`virtctl vnc --kubeconfig=$KUBECONFIG <vmi_name>`
-|Open a Virtual Network Client (VNC) connection to a VMI.
+|`virtctl ssh -i <ssh_key> <user_name>@<vm_name>`
+|Open an SSH connection with a VM. This command uses the private key of an SSH key pair. The VM must be configured with the public key.
 
-Accessing the graphical console of a VMI through VNC requires a remote viewer on your local machine.
+|`virtctl vnc --kubeconfig=$KUBECONFIG <vm_name>`
+|Connect to the VNC console of a VM.
 
-|`virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vmi_name>`
-|Display the port number and connect manually to a VMI by using any viewer through the VNC connection.
+Accessing the graphical console of a VM through VNC requires a remote viewer on your local machine.
 
-|`virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vmi_name>`
+|`virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vm_name>`
+|Display the port number and connect manually to a VM by using any viewer through the VNC connection.
+
+|`virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vm_name>`
 |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.
 |===
 
 [id='vm-volume-export-commands_{context}']
-== VM volume export commands
+== VM export commands
 
-You can use `virtctl vmexport` commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC).
+You use `virtctl vmexport` commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC).
 
-.`virtctl vmexport` commands
+.VM export commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
@@ -130,7 +167,7 @@ Optional:
 [id='vm-memory-dump-commands_{context}']
 == VM memory dump commands
 
-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.
+You can use the `virtctl memory-dump` command to output a VM memory dump on a PVC. You can specify an existing PVC or use the `--create-claim` flag to create a new PVC.
 
 .Prerequisites
 
@@ -158,7 +195,7 @@ $ virtctl vmexport download <vmexport_name> --vm\|pvc=<object_name> \
   --volume=<volume_name> --output=<output_file>
 ----
 
-.`virtctl memory-dump` commands
+.VM memory dump commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
@@ -185,37 +222,41 @@ You must remove a memory dump manually if you want to change the target PVC.
 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.
 |===
 
-[id='image-upload-commands_{context}']
-== Image upload commands
+// hot-plug/unplug NICs will be added in 4.14
+[id="hot-plug-and-hot-unplug-commands_{context}"]
+== Hot plug and hot unplug commands
 
-You can use the `virtctl image-upload` commands to upload a VM image to a data volume.
+You use `virtctl` to add or remove resources from running VMs and VMIs.
 
-.`virtctl image-upload` commands
+.Hot plug and hot-unplug commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
-|`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`
-|Upload a VM image to a data volume that already exists.
+|`virtctl addvolume <vm_name> --volume-name=<datavolume_or_PVC> [--persist] [--serial=<label>]`
+|Hot plug a virtual disk by attaching a data volume or persistent volume claim (PVC) to a running VM.
 
-|`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`
-|Upload a VM image to a new data volume of a specified requested size.
+Optional:
+
+* `--persist` mounts the virtual disk permanently on a VM. This flag does not apply to VMIs.
+* `--serial=<label>` adds a label to the VM. If you do not specify a label, the default label is the data volume or PVC name.
+
+|`virtctl removevolume <vm_name> --volume-name=<datavolume|PVC>`
+|Hot unplug a virtual disk from a running VM.
 |===
 
-[id='environment-information-commands_{context}']
-== Environment information commands
+[id='image-upload-commands_{context}']
+== Image upload commands
 
-You can use `virtctl` to view information about versions, file systems, guest operating systems, and logged-in users.
+You use the `virtctl image-upload` commands to upload a VM image to a data volume.
 
-.`virtctl` environment information commands
+.Image upload commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
-|`virtctl fslist <vmi_name>`
-|View the file systems available on a guest machine.
-
-|`virtctl guestosinfo <vmi_name>`
-|View information about the operating systems on a guest machine.
+|`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`
+|Upload a VM image to a data volume that already exists.
 
-|`virtctl userlist <vmi_name>`
-|View the logged-in users on a guest machine.
+|`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`
+|Upload a VM image to a new data volume of a specified requested size.
 |===
+

modules/virt-virtctl-commands.adoc

@@ -21,7 +21,7 @@ Plan and install {VirtProductName} on an {product-title} cluster:
 * xref:../installing/installing_bare_metal/preparing-to-install-on-bare-metal.adoc#virt-planning-bare-metal-cluster-for-ocp-virt_preparing-to-install-on-bare-metal[Plan your bare metal cluster for {VirtProductName}].
 * xref:../virt/install/preparing-cluster-for-virt.adoc#preparing-cluster-for-virt[Prepare your cluster for {VirtProductName}].
 * xref:../virt/install/installing-virt-web.adoc#virt-installing-virt-operator_installing-virt-web[Install the {VirtProductName} Operator].
-* xref:../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[Install the `virtctl` command line interface (CLI) tool].
+* xref:../virt/virt-using-the-cli-tools.adoc#installing-virtctl_virt-using-the-cli-tools[Install the `virtctl` command line interface (CLI) tool].
 
 [discrete]
 [id="additional-resources_planning-and-installing"]