must-gather
is a tool built on top of OpenShift must-gather
that expands its capabilities to gather KubeVirt information.
oc adm must-gather --image=quay.io/kubevirt/must-gather
The command above will create a local directory with a dump of the KubeVirt state. Note that this command will only get data related to the KubeVirt part of the OpenShift cluster.
You will get a dump of:
- The Hyperconverged Cluster Operator namespaces (and its children objects)
- All namespaces (and their children objects) that belong to any KubeVirt resources
- All KubeVirt CRD's definitions
By default, the VMs definitions won't be included, but only the VM Instances' custom resources.
In order to get data about other parts of the cluster (not specific to KubeVirt) you should
run oc adm must-gather
(without passing a custom image). Run oc adm must-gather -h
to see more options.
Some gathering activity can be done in parallel. Collecting resources one by one may be slow, and collecting too many
resources in parallel may fail. By default, 5 processes are running in parallel, and the rest of the processes are
waiting for running processes to complete. It is possible to change this default number of processes by setting the
PROS
environment variable, but then, the default command must be specified as well, like this:
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
-- PROS=7 \
/usr/bin/gather
To collect the VM information, and all the namespaces that contains VMs call directly the gather_vms_details
command:
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
-- /usr/bin/gather_vms_details
The gather_vms_details
command supports targeted gathering. By specifying a namespace, the command will only
collect the VMs in this namespace. For example, collecting all the VM information in namespace "vm1":
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
-- NS=ns1 \
/usr/bin/gather_vms_details
By specifying the VM name in addition to the namespace, the gather_vms_details
command will only collect the specific
VM information. For example, collecting the information of a specific VM called "testvm" in namespace "vm1":
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
-- NS=ns1 \
VM=testvm \
/usr/bin/gather_vms_details
Note: When collecting information for a specific VM, you must specify the namespace as well. Without the namespace,
the gather_vms_details
command exits and prints an error message.
The VM
environment variable can also be a comma-seperated list of VM names (without a space). For example:
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
-- NS=ns1 \
VM="testvm1,testvm34,testvm52,testvm74", \
/usr/bin/gather_vms_details
The gather_vms_details
command also support gathering VM with regex expression.
For example, suppose we have the following VMs in the cluster:
testvm1-1 testvm1-2 testvm1-3 testvm1-4 testvm1-5
testvm1-6 testvm1-7 testvm1-8 testvm1-9 testvm1-10
testvm2-1 testvm2-2 testvm2-3 testvm2-4 testvm2-5
testvm2-6 testvm2-7 testvm2-8 testvm2-9 testvm2-10
testvm3-1 testvm3-2 testvm3-3 testvm3-4 testvm3-5
testvm3-6 testvm3-7 testvm3-8 testvm3-9 testvm3-10
testvm4-1 testvm4-2 testvm4-3 testvm4-4 testvm4-5
testvm4-6 testvm4-7 testvm4-8 testvm4-9 testvm4-10
testvm5-1 testvm5-2 testvm5-3 testvm5-4 testvm5-5
testvm5-6 testvm5-7 testvm5-8 testvm5-9 testvm5-10
If we want to read only VMs that starts with testvm2, testvm3 or testvm4, and that their postfix number is odd, we can use this regex expression to for that: ^testvm[2-4]-[0-9]*[1,3,5,7,9]$
.
Here is how to use it in the gather_vms_details
command, to search VMs by regex:
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
VM_EXP="^testvm[2-4]-[0-9]*[1,3,5,7,9]$", \
/usr/bin/gather_vms_details
Here is how to use it in the gather_vms_details
command, to search VMs by regex in the ns1
namespace:
oc adm must-gather \
--image=quay.io/kubevirt/must-gather \
-- NS=ns1 \
VM_EXP="^testvm[2-4]-[0-9]*[1,3,5,7,9]$", \
/usr/bin/gather_vms_details
Note: When collecting information using the VM
variable, the command will ignore the VM_EPR
variable. Do not use both of them together.
It is possible to collect image, image-stream and image-stream-tags information using the gather_images
command:
oc adm must-gather --image=quay.io/kubevirt/must-gather -- /usr/bin/gather_images
The gather_vms_details
and the gather_images
commands support parallelism as well. To change the default number of processes of 5, add the
PROS
environment variable. This is only works when not using the NS
environment variable:
oc adm must-gather --image=quay.io/kubevirt/must-gather -- PROS=7 /usr/bin/gather_vms_details
Or
oc adm must-gather --image=quay.io/kubevirt/must-gather -- PROS=3 /usr/bin/gather_images
You can build the image locally using the Dockerfile included.
A makefile
is also provided. To use it, you must pass a repository via the command-line using the variable MUST_GATHER_IMAGE
.
You can also specify the registry using the variable IMAGE_REGISTRY
(default is quay.io) and the tag via IMAGE_TAG
(default is latest
).
The targets for make
are as follows:
build
: builds the image with the supplied name and pushes itdocker-build
: builds the image but does not push itdocker-push
: pushes an already-built image
For example:
make build MUST_GATHER_IMAGE=kubevirt/must-gather
would build the local repository as quay.io/kubevirt/must-gather:latest
and then push it.