Merge pull request #35825 from mgarrellRH/CNV11177

CNV11177: Adding info about the virtctl guestfs command

Author: ousleyp

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

@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// * virt/virt-using-the-cli-tools.adoc
+
+[id="virt-about-libguestfs-tools-virtctl-guestfs_{context}"]
+= Libguestfs tools and virtctl guestfs
+
+`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.
+
+You can also use the `virtctl guestfs` command and its sub-commands to modify, inspect, and debug VM disks on a PVC. To see a complete list of possible sub-commands, enter `virt-` on the command line and press the Tab key. For example:
+
+[width="100%",cols="42%,58%",options="header",]
+|===
+|Command |Description
+
+|`virt-edit -a /dev/vda /etc/motd`
+|Edit a file interactively in your terminal.
+
+|`virt-customize -a /dev/vda --ssh-inject root:string:<public key example>`
+|Inject an ssh key into the guest and create a login.
+
+|`virt-df -a /dev/vda -h`
+|See how much disk space is used by a VM.
+
+|`virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'`
+|See the full list of all RPMs installed on a guest by creating an output file containing the full list.
+
+|`virt-cat -a /dev/vda /rpm-list`
+|Display the output file list of all RPMs created using the `virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'` command in your terminal.
+
+|`virt-sysprep -a /dev/vda`
+|Seal a virtual machine disk image to be used as a template.
+|===
+
+By default, `virtctl guestfs` creates a session with everything needed to manage a VM disk. However, the command also supports several flag options if you want to customize the behavior:
+
+[width="100%",cols="42%,58%",options="header",]
+|===
+|Flag Option |Description
+
+|`--h` or `--help`
+|Provides help for `guestfs`.
+
+|`-n <namespace>` option with a `<pvc_name>` argument
+|To use a PVC from a specific namespace.
+
+If you do not use the `-n <namespace>` option, your current project is used. To change projects, use `oc project <namespace>`.
+
+If you do not include a `<pvc_name>` argument, an error message appears.
+
+|`--image string`
+|Lists the `libguestfs-tools` container image.
+
+You can configure the container to use a custom image by using the `--image` option.
+
+|`--kvm`
+|Indicates that `kvm` is used by the `libguestfs-tools` container.
+
+By default, `virtctl guestfs` sets up `kvm` for the interactive container, which greatly speeds up the `libguest-tools` execution because it uses QEMU.
+
+If a cluster does not have any `kvm` supporting nodes, you must disable `kvm` by setting the option `--kvm=false`.
+
+If not set, the `libguestfs-tools` pod remains pending because it cannot be scheduled on any node.
+
+|`--pull-policy string`
+|Shows the pull policy for the `libguestfs` image.
+
+You can also overwrite the image's pull policy by setting the `pull-policy` option.
+|===
+
+The command also checks if a PVC is used by another pod and fails if the PVC is used by another pod. However, once the `libguestfs-tools` process starts, the setup cannot avoid a new pod using the same PVC. You must verify that there are no active `virtctl guestfs` pods before starting the VM that accesses the same PVC.
+
+[NOTE]
+=====
+The `virtctl guestfs` command accepts only a single PVC attached to the interactive pod.
+=====

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

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * virt/virt-using-the-cli-tools.adoc
+
+[id="virt-creating-pvc-with-virtctl-guestfs_{context}"]
+= Creating a container using virtctl guestfs
+
+You can use the `virtctl guestfs` command to deploy an interactive container with `libguestfs-tools` and a persistent volume claim (PVC) attached to it.
+
+.Procedure
+
+* To deploy a container with `libguestfs-tools`, mount the PVC, and attach a shell to it, run the following command:
++
+[source,terminal]
+----
+$ virtctl guestfs -n <namespace> <pvc_name> <1>
+----
+<1> The PVC name is a required argument. If you do not include it, an error message appears.

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

@@ -14,8 +14,16 @@ The two primary CLI tools used for managing resources in the cluster are:
 
 * You must xref:../virt/install/virt-enabling-virtctl.adoc#virt-enabling-virtctl[enable the `virtctl` client].
 
-include::modules/virt-virtctl-commands.adoc[leveloffset=+1]
 include::modules/virt-openshift-client-commands.adoc[leveloffset=+1]
 
 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.
+
+include::modules/virt-virtctl-commands.adoc[leveloffset=+1]
+include::modules/virt-creating-pvc-with-virtctl-guestfs.adoc[leveloffset=+1]
+include::modules/virt-about-libguestfs-tools-virtctl-guestfs.adoc[leveloffset=+1]
+
+[id="additional-resources_virt-using-the-cli-tools"]
+== Additional resources
+
+* link:https://libguestfs.org[Libguestfs: tools for accessing and modifying virtual machine disk images].