Update virtctl commands

apinnick · apinnick · commit d2112a52e918 · 2023-06-26T19:03:16.000+03:00
Signed-off-by: Avital Pinnick &lt;apinnick@redhat.com&gt;
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -542,7 +542,7 @@ Topics:
   File: bare-metal-configuration
 - Name: Configuring multi-architecture compute machines on an OpenShift cluster
   Distros: openshift-enterprise
-  File: multi-architecture-configuration 
+  File: multi-architecture-configuration
 - Name: Enabling encryption on a vSphere cluster
   File: vsphere-post-installation-encryption
 - Name: Machine configuration tasks
@@ -2290,7 +2290,7 @@ Topics:
     File: nodes-cma-autoscaling-custom-trigger
   - Name: Understanding the custom metrics autoscaler trigger authentications
     File: nodes-cma-autoscaling-custom-trigger-auth
-  - Name: Pausing the custom metrics autoscaler 
+  - Name: Pausing the custom metrics autoscaler
     File: nodes-cma-autoscaling-custom-pausing
   - Name: Gathering audit logs
     File: nodes-cma-autoscaling-custom-audit-log
@@ -3632,8 +3632,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
@@ -3648,7 +3646,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
diff --git a/modules/virt-about-libguestfs-tools-virtctl-guestfs.adoc b/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.
 
diff --git a/modules/virt-creating-pvc-with-virtctl-guestfs.adoc b/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.
 
diff --git a/modules/virt-installing-virtctl-client-yum.adoc b/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]
diff --git a/modules/virt-installing-virtctl-client.adoc b/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`:
 
diff --git a/modules/virt-openshift-client-commands.adoc b/modules/virt-openshift-client-commands.adoc
diff --git a/modules/virt-virtctl-commands.adoc b/modules/virt-virtctl-commands.adoc
@@ -8,7 +8,10 @@
 
 The `virtctl` client is a command-line utility for managing {VirtProductName} resources.
 
-Although the examples refer to virtual machines (VMs), you can use these commands with virtual machine instances (VMIs).
+[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.
@@ -38,7 +41,7 @@ You use `virtctl` information commands to view information about the `virtctl` c
 [id='vm-information-commands_{context}']
 == VM information commands
 
-You can use `virtctl` to view information about VMs.
+You can use `virtctl` to view information about VMs and VMIs.
 
 .VM information commands
 [width="100%",cols="1a,2a",options="header"]
@@ -57,7 +60,7 @@ You can use `virtctl` to view information about VMs.
 [id='vm-management-commands_{context}']
 == VM management commands
 
-You use `virtctl` virtual machine (VM) management commands to manage VMs.
+You use `virtctl` virtual machine (VM) management commands to manage and migrate VMs and VMIs.
 
 .VM management commands
 [width="100%",cols="1a,2a",options="header"]
@@ -78,7 +81,7 @@ You use `virtctl` virtual machine (VM) management commands to manage VMs.
 |`virtctl pause vm <vm_name>`
 |Pause a VM. The machine state is kept in memory.
 
-|`virtctl unpause vm\|vmi <vm_name>`
+|`virtctl unpause vm <vm_name>`
 |Unpause a VM.
 
 |`virtctl migrate <vm_name>`
@@ -88,10 +91,10 @@ You use `virtctl` virtual machine (VM) management commands to manage VMs.
 |Restart a VM.
 |===
 
-[id='vm-and-vmi-connection-commands_{context}']
+[id='vm-connection-commands_{context}']
 == VM connection commands
 
-You use `virtctl` connection commands to expose ports and connect to virtual machines (VMs).
+You use `virtctl` connection commands to expose ports and connect to VMs and VMIs.
 
 .VM connection commands
 [width="100%",cols="1a,2a",options="header"]
@@ -103,22 +106,22 @@ You use `virtctl` connection commands to expose ports and connect to virtual mac
 |`virtctl expose <vm_name>`
 |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> <filename> <vm_username>@<vm_name>`
-|Copy a file from your machine to a VM. The command uses the private key of an SSH key pair. The VM must be configured with its public key.
+|`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> <vm_username@<vm_name>:<filename> .`
-|Copy a file from a VM to your machine. The command uses the private key of an SSH key pair. The VM must be configured with its 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 ssh -i <ssh_key> <user_name>@<vm_name>`
-|Open an SSH connection with a VM. The command uses the private key of an SSH key pair. The VM must be configured with its public key.
+|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.
 
 |`virtctl vnc --kubeconfig=$KUBECONFIG <vm_name>`
 |Connect to the VNC console of a VM.
 
 Accessing the graphical console of a VM through VNC requires a remote viewer on your local machine.
 
 |`virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vm_name>`
-|Display the port number and connect manually to a VMI by using any viewer through the VNC connection.
+|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.
@@ -129,7 +132,7 @@ If a port number is not specified, the proxy runs on a random port.
 [id='vm-volume-export-commands_{context}']
 == 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).
 
 .VM export commands
 [width="100%",cols="1a,2a",options="header"]
@@ -164,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
 
@@ -219,10 +222,32 @@ 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.
 |===
 
+// 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 use `virtctl` to add or remove resources from running VMs and VMIs.
+
+.Hot plug and hot-unplug commands
+[width="100%",cols="1a,2a",options="header"]
+|===
+|Command |Description
+|`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.
+
+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='image-upload-commands_{context}']
 == Image upload commands
 
-You can use the `virtctl image-upload` commands to upload a VM image to a data volume.
+You use the `virtctl image-upload` commands to upload a VM image to a data volume.
 
 .Image upload commands
 [width="100%",cols="1a,2a",options="header"]
diff --git a/virt/install/virt-installing-virtctl.adoc b/virt/install/virt-installing-virtctl.adoc
diff --git a/virt/virt-getting-started.adoc b/virt/virt-getting-started.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"]
diff --git a/virt/virt-using-the-cli-tools.adoc b/virt/virt-using-the-cli-tools.adoc
@@ -1,33 +1,32 @@
 :_content-type: ASSEMBLY
 [id="virt-using-the-cli-tools"]
-= Using the virtctl and oc tools
+= Using virtctl and libguestfs
 include::_attributes/common-attributes.adoc[]
 :context: virt-using-the-cli-tools
 :toclevels: 3
 
 toc::[]
 
-You use two primary CLI tools used for managing cluster resources:
+You can manage {VirtProductName} resources by using the `virtctl` command line tool.
 
-* {VirtProductName} `virtctl` client
-+
-See xref:../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[Installing the `virtctl` client].
+You can also deploy a `libguestfs-tools` container by using `virtctl`. link:https://libguestfs.org[`Libguestfs`] is a set of tools for accessing and modifying virtual machine (VM) disk images.
 
-* {product-title} `oc` client
+[id="installing-virtctl_virt-using-the-cli-tools"]
+== Installing virtctl
 
-include::modules/virt-openshift-client-commands.adoc[leveloffset=+1]
+To install `virtctl` on Linux, Windows, and MacOS operating systems, you download  and install the the `virtctl` binary file.
 
-For more comprehensive information on `oc` client commands, see the
-xref:../cli_reference/openshift_cli/developer-cli-commands.adoc#cli-developer-commands[{product-title} CLI tools] documentation.
+To install `virtctl` on {op-system-base-full}, you enable the {VirtProductName} repository and then install the `kubevirt-virtctl` package.
+
+include::modules/virt-installing-virtctl-client.adoc[leveloffset=+2]
+
+include::modules/virt-installing-virtctl-client-yum.adoc[leveloffset=+2]
 
 include::modules/virt-virtctl-commands.adoc[leveloffset=+1]
 
-include::modules/virt-creating-pvc-with-virtctl-guestfs.adoc[leveloffset=+1]
+== Using libguestfs
 
-include::modules/virt-about-libguestfs-tools-virtctl-guestfs.adoc[leveloffset=+1]
+include::modules/virt-creating-pvc-with-virtctl-guestfs.adoc[leveloffset=+2]
 
-[id="additional-resources_virt-using-the-cli-tools"]
-[role="_additional-resources"]
-== Additional resources
+include::modules/virt-about-libguestfs-tools-virtctl-guestfs.adoc[leveloffset=+2]
 
-* link:https://libguestfs.org[Libguestfs: tools for accessing and modifying virtual machine disk images].
diff --git a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc b/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc
@@ -15,7 +15,7 @@ to upload the local disk image into the PVC.
 
 == Prerequisites
 
-* xref:../../../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[Install `virtctl`].
+* xref:../../../virt/virt-using-the-cli-tools.adoc#installing-virtctl_virt-using-the-cli-tools[Install `virtctl`].
 
 * You might need to xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space]
 for this operation to complete successfully.
diff --git a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc b/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc
@@ -10,7 +10,7 @@ You can upload a locally stored disk image to a new or existing persistent volum
 
 == Prerequisites
 
-* xref:../../../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[Install `virtctl`].
+* xref:../../../virt/virt-using-the-cli-tools.adoc#installing-virtctl_virt-using-the-cli-tools[Install `virtctl`].
 
 * You might need to xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space]
 for this operation to complete successfully.
