Controlling virtual machine states

You can use virtctl to manage virtual machine states and perform other actions from the CLI. For example, you can use virtctl to force stop a VM or expose a port.

You can stop, start, restart, pause, and unpause virtual machines from the web console.

Configuring RBAC permissions for managing VM states by using the web console

To allow users to manage virtual machine (VM) states by using the OpenShift Container Platform web console, you must create an RBAC cluster role and cluster role binding. The cluster role uses the subresources.kubevirt.io API to define which resources can be controlled by certain users or groups.

Prerequisites

You have cluster administrator access to an OpenShift Container Platform cluster where OpenShift Virtualization is installed.
You have installed the OpenShift CLI (oc).

Procedure

Create a ClusterRole object that allows the target user or group to manage VM states:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: vm-manager-access
rules:
  - apiGroups:
      - subresources.kubevirt.io
    resources:
      - virtualmachines/start
      - virtualmachines/stop
    verbs:
      - put
# ...

Run the following command to apply the cluster role:
```
$ oc apply -f <filename>.yaml
```
Confirm that the cluster role was created by running the following command and observing the output:
```
$ oc get clusterrole <name>
```
Example output:
```
NAME                AGE
vm-manager-access   15s
```

Inspect the details of the cluster role, and ensure the intended rules for subresources.kubevirt.io are present, specifically the virtualmachines/start and virtualmachines/stop subresources.

Run the following command and observe the output:

$ oc describe clusterrole <name>

Example output:

Name:         vm-manager-access
Labels:       <none>
Annotations:  <none>
PolicyRule:
  Resources  Non-Resource URLs  Resource Names  Verbs
  ---------  -----------------  --------------  -----
  virtualmachines/start, virtualmachines/stop with subresources.kubevirt.io group  []  []  [put]

Create a ClusterRoleBinding object to bind the cluster role you have created to the target user or group:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: vm-manager-access-binding
subjects:
  - kind: User
    name: test-user
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: vm-manager-access
  apiGroup: rbac.authorization.k8s.io

Run the following command to apply the cluster role binding:
```
$ oc apply -f <filename>.yaml
```
Confirm that the cluster role binding was created by running the following command and observing the output:
```
$ oc get clusterrolebinding <name>
```
Example output:
```
NAME                        AGE
vm-manager-access-binding   15s
```

Verification

Check if the user can start a VM by running the following command:

$ oc auth can-i update virtualmachines/start --namespace=<namespace> --as=<user_name> --subresource=subresources.kubevirt.io

Example output:

yes

Check if the user can stop a VM by running the following command:

$ oc auth can-i update virtualmachines/stop --namespace=<namespace> --as=<user_name> --group=subresources.kubevirt.io

Example output:

yes

Enabling confirmations of virtual machine actions

The Stop, Restart, and Pause actions can display confirmation dialogs if confirmation is enabled. By default, confirmation is disabled.

Procedure

In the Virtualization section of the OpenShift Container Platform web console, navigate to Overview → Settings → Cluster → General settings.
Toggle the VirtualMachine actions confirmation setting to On.

Starting a virtual machine

You can start a virtual machine (VM) from the web console.

Procedure

Click Virtualization → VirtualMachines from the side menu.
In the tree view, select the project that contains the VM that you want to start.
Navigate to the appropriate menu for your use case:
- To stay on this page, where you can perform actions on multiple VMs:
  1. Click the Options menu located at the far right end of the row and click Start VirtualMachine.
- To start the VM from the tree view:
  1. Click the > icon next to the project name to open the list of VMs.
  2. Right-click the name of the VM and select Start.
- To view comprehensive information about the selected VM before you start it:
  1. Access the VirtualMachine details page by clicking the name of the VM.
  2. Click Actions → Start.
    
    Note
    
    When you start VM that is provisioned from a URL source for the first time, the VM has a status of Importing while OpenShift Virtualization imports the container from the URL endpoint. Depending on the size of the image, this process might take several minutes.

Stopping a virtual machine

You can stop a virtual machine (VM) from the web console.

Procedure

Click Virtualization → VirtualMachines from the side menu.
In the tree view, select the project that contains the VM that you want to stop.
Navigate to the appropriate menu for your use case:
- To stay on this page, where you can perform actions on multiple VMs:
  1. Click the Options menu located at the far right end of the row and click Stop VirtualMachine.
  2. If action confirmation is enabled, click Stop in the confirmation dialog.
- To stop the VM from the tree view:
  1. Click the > icon next to the project name to open the list of VMs.
  2. Right-click the name of the VM and select Stop.
  3. If action confirmation is enabled, click Stop in the confirmation dialog.
- To view comprehensive information about the selected VM before you stop it:
  1. Access the VirtualMachine details page by clicking the name of the VM.
  2. Click Actions → Stop.
  3. If action confirmation is enabled, click Stop in the confirmation dialog.

Restarting a virtual machine

You can restart a running virtual machine (VM) from the web console.

Important

To avoid errors, do not restart a VM while it has a status of Importing.

Procedure

Click Virtualization → VirtualMachines from the side menu.
In the tree view, select the project that contains the VM that you want to restart.
Navigate to the appropriate menu for your use case:
- To stay on this page, where you can perform actions on multiple VMs:
  1. Click the Options menu located at the far right end of the row and click Restart.
  2. If action confirmation is enabled, click Restart in the confirmation dialog.
- To restart the VM from the tree view:
  1. Click the > icon next to the project name to open the list of VMs.
  2. Right-click the name of the VM and select Restart.
  3. If action confirmation is enabled, click Restart in the confirmation dialog.
- To view comprehensive information about the selected VM before you restart it:
  1. Access the VirtualMachine details page by clicking the name of the virtual machine.
  2. Click Actions → Restart.
  3. If action confirmation is enabled, click Restart in the confirmation dialog.

Pausing a virtual machine

You can pause a virtual machine (VM) from the web console.

Procedure

Click Virtualization → VirtualMachines from the side menu.
In the tree view, select the project that contains the VM that you want to pause.
Navigate to the appropriate menu for your use case:
- To stay on this page, where you can perform actions on multiple VMs:
  1. Click the Options menu located at the far right end of the row and click Pause VirtualMachine.
  2. If action confirmation is enabled, click Pause in the confirmation dialog.
- To pause the VM from the tree view:
  1. Click the > icon next to the project name to open the list of VMs.
  2. Right-click the name of the VM and select Pause.
  3. If action confirmation is enabled, click Pause in the confirmation dialog.
- To view comprehensive information about the selected VM before you pause it:
  1. Access the VirtualMachine details page by clicking the name of the VM.
  2. Click Actions → Pause.
  3. If action confirmation is enabled, click Pause in the confirmation dialog.

Unpausing a virtual machine

You can unpause a paused virtual machine (VM) from the web console.

Prerequisites

At least one of your VMs must have a status of Paused.

Procedure

Click Virtualization → VirtualMachines from the side menu.
In the tree view, select the project that contains the VM that you want to unpause.
Navigate to the appropriate menu for your use case:
- To stay on this page, where you can perform actions on multiple VMs:
  1. Click the Options menu located at the far right end of the row and click Unpause VirtualMachine.
- To unpause the VM from the tree view:
  1. Click the > icon next to the project name to open the list of VMs.
  2. Right-click the name of the VM and select Unpause.
- To view comprehensive information about the selected VM before you unpause it:
  1. Access the VirtualMachine details page by clicking the name of the virtual machine.
  2. Click Actions → Unpause.

Controlling the state of multiple virtual machines

You can start, stop, restart, pause, and unpause multiple virtual machines (VMs) from the web console.

Procedure

Navigate to Virtualization → VirtualMachines in the web console.
Optional: Enable the Show only projects with VirtualMachines option above the tree view to limit the displayed projects.
Select a relevant project from the tree view.
Navigate to the appropriate menu for your use case:
- To change the state of all VMs in the selected project:
  1. Right-click the name of the project in the tree view and select the intended action from the menu.
  2. If action confirmation is enabled, confirm the action in the confirmation dialog.
- To change the state of specific VMs:
  1. Select a checkbox next to the VMs you want to work with. To select all VMs, click the checkbox in the VirtualMachines table header.
  2. Click Actions and select the intended action from the menu.
  3. If action confirmation is enabled, confirm the action in the confirmation dialog.