Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 10. Using the CLI tools

The two primary CLI tools used for managing resources in the cluster are:

  • The OpenShift Virtualization 
    virtctl
    client
  • The OpenShift Container Platform 
    oc
    client

10.1. Prerequisites
Link kopieren

10.2. OpenShift Container Platform client commands
Link kopieren

The OpenShift Container Platform 

oc
client is a command-line utility for managing OpenShift Container Platform resources, including the 
VirtualMachine
(
vm
) and 
VirtualMachineInstance
(
vmi
) object types.

Note

You can use the 

-n <namespace>
flag to specify a different project.

Expand
Table 10.1. oc commands
CommandDescription

oc login -u <user_name>

Log in to the OpenShift Container Platform cluster as 

<user_name>
. 

oc get <object_type>

Display a list of objects for the specified object type in the current project. 

oc describe <object_type> <resource_name>

Display details of the specific resource in the current project. 

oc create -f <object_config>

Create a resource in the current project from a file name or from stdin. 

oc edit <object_type> <resource_name>

Edit a resource in the current project. 

oc delete <object_type> <resource_name>

Delete a resource in the current project.

For more comprehensive information on 

oc
client commands, see the OpenShift Container Platform CLI tools documentation.

10.3. Virtctl commands
Link kopieren

The 

virtctl
client is a command-line utility for managing OpenShift Virtualization resources.

Expand
Table 10.2. virtctl general commands
CommandDescription

virtctl version

View the 

virtctl
client and server versions. 

virtctl help

View a list of 

virtctl
commands. 

virtctl <command> -h|--help

View a list of options for a specific command. 

virtctl options

View a list of global command options for any 

virtctl
command.

10.3.1. VM and VMI management commands
Link kopieren

You can use 

virtctl
to manage virtual machine (VM) or virtual machine instance (VMI) states and to migrate a VM.

Expand
Table 10.3. virtctl VM management commands
CommandDescription

virtctl start <vm_name>

Start a VM. 

virtctl start --paused <vm_name>

Start a VM in a paused state. This option enables you to interrupt the boot process from the VNC console. 

virtctl stop <vm_name>

Stop a VM. 

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 unpause vm|vmi <vm_name>

Unpause a VM or VMI. 

virtctl migrate <vm_name>

Migrate a VM. 

virtctl restart <vm_name>

Restart a VM.

10.3.2. VM and VMI connection commands
Link kopieren

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.

Expand
Table 10.4. virtctl console, expose, and vnc commands
CommandDescription

virtctl console <vmi_name>

Connect to the serial console of a VMI. 

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. 

virtctl vnc --kubeconfig=$KUBECONFIG <vmi_name>

Open a Virtual Network Client (VNC) connection to a VMI.

Accessing the graphical console of a VMI through VNC requires a remote viewer on your local machine. 

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. 

virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vmi_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.

10.3.3. VM volume export commands
Link kopieren

You can use 

virtctl vmexport
commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC).

Expand
Table 10.5. virtctl vmexport commands
CommandDescription

virtctl vmexport create <vmexport_name> --vm|snapshot|pvc=<object_name>

Create a 

VirtualMachineExport
custom resource (CR) to export a volume from a VM, VM snapshot, or PVC. 

  • --vm
    : Exports the PVCs of a VM. 
  • --snapshot
    : Exports the PVCs contained in a 
    VirtualMachineSnapshot
    CR. 
  • --pvc
    : Exports a PVC.
  • Optional: 
    --ttl=1h
    specifies the time to live. The default duration is 2 hours. 

virtctl vmexport delete <vmexport_name>

Delete a 

VirtualMachineExport
CR manually. 

virtctl vmexport download <vmexport_name> --output=<output_file> --volume=<volume_name>

Download the volume defined in a 

VirtualMachineExport
CR. 

  • --output
    specifies the file format. Example: 
    disk.img.gz
    . 
  • --volume
    specifies the volume to download. This flag is optional if only one volume is available.

Optional: 

  • --keep-vme
    retains the 
    VirtualMachineExport
    CR after download. The default behavior is to delete the 
    VirtualMachineExport
    CR after download. 
  • --insecure
    enables an insecure HTTP connection. 

virtctl vmexport download <vmexport_name> --<vm|snapshot|pvc>=<object_name> --output=<output_file> --volume=<volume_name>

Create a 

VirtualMachineExport
CR and then download the volume defined in the CR.

10.3.4. VM memory dump commands
Link kopieren

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.

Prerequisites

  • The PVC volume mode must be 
    FileSystem
    .

  • The PVC must be large enough to contain the memory dump.

    The formula for calculating the PVC size is 

    (VMMemorySize + 100Mi) * FileSystemOverhead
    , where 
    100Mi
    is the memory dump overhead.

  • You must enable the hot plug feature gate in the 

    HyperConverged
    custom resource by running the following command: 

    $ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
  --type json -p '[{"op": "add", "path": "/spec/featureGates", \
  "value": "HotplugVolumes"}]'

Downloading the memory dump

You must use the 

virtctl vmexport download
command to download the memory dump: 

$ virtctl vmexport download <vmexport_name> --vm\|pvc=<object_name> \
  --volume=<volume_name> --output=<output_file>
Expand
Table 10.6. virtctl memory-dump commands
CommandDescription

virtctl memory-dump get <vm_name> --claim-name=<pvc_name>

Save the memory dump of a VM on a PVC. The memory dump status is displayed in the 

status
section of the 
VirtualMachine
resource.

Optional: 

  • --create-claim
    creates a new PVC with the appropriate size. This flag has the following options: 

    • --storage-class=<storage_class>
      : Specify a storage class for the PVC. 
    • --access-mode=<access_mode>
      : Specify 
      ReadWriteOnce
      or 
      ReadWriteMany
      . 

virtctl memory-dump get <vm_name>

Rerun the 

virtctl memory-dump
command with the same PVC.

This command overwrites the previous memory dump. 

virtctl memory-dump remove <vm_name>

Remove a memory dump.

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.

10.3.5. Image upload commands
Link kopieren

You can use the 

virtctl image-upload
commands to upload a VM image to a data volume.

Expand
Table 10.7. virtctl image-upload commands
CommandDescription

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 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.

10.3.6. Environment information commands
Link kopieren

You can use 

virtctl
to view information about versions, file systems, guest operating systems, and logged-in users.

Expand
Table 10.8. virtctl environment information commands
CommandDescription

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 userlist <vmi_name>

View the logged-in users on a guest machine.

10.4. Creating a container using virtctl guestfs
Link kopieren

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: 

    $ virtctl guestfs -n <namespace> <pvc_name>
    Important

    The 

    <pvc_name>
    argument is required. If you do not include it, an error message appears.

10.5. Libguestfs tools and virtctl guestfs
Link kopieren

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:

Expand
CommandDescription

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:

Expand
Flag OptionDescription

--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 in use by another pod, in which case an error message appears. 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.

Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red HatNach oben