×

You can create and delete virtual machine (VM) snapshots for VMs, whether the VMs are powered off (offline) or on (online). You can only restore to a powered off (offline) VM. OKD Virtualization supports VM snapshots on the following:

  • Red Hat OpenShift Data Foundation

  • Any other cloud storage provider with the Container Storage Interface (CSI) driver that supports the Kubernetes Volume Snapshot API

Online snapshots have a default time deadline of five minutes (5m) that can be changed, if needed.

Online snapshots are supported for virtual machines that have hot-plugged virtual disks. However, hot-plugged disks that are not in the virtual machine specification are not included in the snapshot.

To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.

The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.

About virtual machine snapshots

A snapshot represents the state and data of a virtual machine (VM) at a specific point in time. You can use a snapshot to restore an existing VM to a previous state (represented by the snapshot) for backup and disaster recovery or to rapidly roll back to a previous development version.

A VM snapshot is created from a VM that is powered off (Stopped state) or powered on (Running state).

When taking a snapshot of a running VM, the controller checks that the QEMU guest agent is installed and running. If so, it freezes the VM file system before taking the snapshot, and thaws the file system after the snapshot is taken.

The snapshot stores a copy of each Container Storage Interface (CSI) volume attached to the VM and a copy of the VM specification and metadata. Snapshots cannot be changed after creation.

With the VM snapshots feature, cluster administrators and application developers can:

  • Create a new snapshot

  • List all snapshots attached to a specific VM

  • Restore a VM from a snapshot

  • Delete an existing VM snapshot

Virtual machine snapshot controller and custom resource definitions (CRDs)

The VM snapshot feature introduces three new API objects defined as CRDs for managing snapshots:

  • VirtualMachineSnapshot: Represents a user request to create a snapshot. It contains information about the current state of the VM.

  • VirtualMachineSnapshotContent: Represents a provisioned resource on the cluster (a snapshot). It is created by the VM snapshot controller and contains references to all resources required to restore the VM.

  • VirtualMachineRestore: Represents a user request to restore a VM from a snapshot.

The VM snapshot controller binds a VirtualMachineSnapshotContent object with the VirtualMachineSnapshot object for which it was created, with a one-to-one mapping.

Installing QEMU guest agent on a Linux virtual machine

The qemu-guest-agent is widely available and available by default in Fedora virtual machines (VMs). Install the agent and start the service.

To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.

The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.

Procedure
  1. Access the virtual machine command line through one of the consoles or by SSH.

  2. Install the QEMU guest agent on the virtual machine:

    $ yum install -y qemu-guest-agent
  3. Ensure the service is persistent and start it:

    $ systemctl enable --now qemu-guest-agent
Verification
  1. Run the following command to verify that AgentConnected is listed in the VM spec:

    $ oc get vm <vm_name>

Installing QEMU guest agent on a Windows virtual machine

For Windows virtual machines, the QEMU guest agent is included in the VirtIO drivers. Install the drivers on an existing or a new Windows installation.

To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.

The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.

Procedure
  1. In the Windows Guest Operating System (OS), use the File Explorer to navigate to the guest-agent directory in the virtio-win CD drive.

  2. Run the qemu-ga-x86_64.msi installer.

Verification
  1. Run the following command to verify that the output contains the QEMU Guest Agent:

    $ net start

Installing VirtIO drivers on an existing Windows virtual machine

Install the VirtIO drivers from the attached SATA CD drive to an existing Windows virtual machine.

This procedure uses a generic approach to adding drivers to Windows. The process might differ slightly between versions of Windows. See the installation documentation for your version of Windows for specific installation steps.

Procedure
  1. Start the virtual machine and connect to a graphical console.

  2. Log in to a Windows user session.

  3. Open Device Manager and expand Other devices to list any Unknown device.

    1. Open the Device Properties to identify the unknown device. Right-click the device and select Properties.

    2. Click the Details tab and select Hardware Ids in the Property list.

    3. Compare the Value for the Hardware Ids with the supported VirtIO drivers.

  4. Right-click the device and select Update Driver Software.

  5. Click Browse my computer for driver software and browse to the attached SATA CD drive, where the VirtIO drivers are located. The drivers are arranged hierarchically according to their driver type, operating system, and CPU architecture.

  6. Click Next to install the driver.

  7. Repeat this process for all the necessary VirtIO drivers.

  8. After the driver installs, click Close to close the window.

  9. Reboot the virtual machine to complete the driver installation.

Creating a virtual machine snapshot in the web console

You can create a virtual machine (VM) snapshot by using the web console.

To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.

The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.

The VM snapshot only includes disks that meet the following requirements:

  • Must be either a data volume or persistent volume claim

  • Belong to a storage class that supports Container Storage Interface (CSI) volume snapshots

Procedure
  1. Click VirtualizationVirtualMachines from the side menu.

  2. Select a virtual machine to open the VirtualMachine details page.

  3. If the virtual machine is running, click ActionsStop to power it down.

  4. Click the Snapshots tab and then click Take Snapshot.

  5. Fill in the Snapshot Name and optional Description fields.

  6. Expand Disks included in this Snapshot to see the storage volumes to be included in the snapshot.

  7. If your VM has disks that cannot be included in the snapshot and you still wish to proceed, select the I am aware of this warning and wish to proceed checkbox.

  8. Click Save.

Creating a virtual machine snapshot in the CLI

You can create a virtual machine (VM) snapshot for an offline or online VM by creating a VirtualMachineSnapshot object. Kubevirt will coordinate with the QEMU guest agent to create a snapshot of the online VM.

To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.

The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.

Prerequisites
  • Ensure that the persistent volume claims (PVCs) are in a storage class that supports Container Storage Interface (CSI) volume snapshots.

  • Install the OpenShift CLI (oc).

  • Optional: Power down the VM for which you want to create a snapshot.

Procedure
  1. Create a YAML file to define a VirtualMachineSnapshot object that specifies the name of the new VirtualMachineSnapshot and the name of the source VM.

    For example:

    apiVersion: snapshot.kubevirt.io/v1beta1
    kind: VirtualMachineSnapshot
    metadata:
      name: my-vmsnapshot (1)
    spec:
      source:
        apiGroup: kubevirt.io
        kind: VirtualMachine
        name: my-vm (2)
    1 The name of the new VirtualMachineSnapshot object.
    2 The name of the source VM.
  2. Create the VirtualMachineSnapshot resource. The snapshot controller creates a VirtualMachineSnapshotContent object, binds it to the VirtualMachineSnapshot and updates the status and readyToUse fields of the VirtualMachineSnapshot object.

    $ oc create -f <my-vmsnapshot>.yaml
  3. Optional: If you are taking an online snapshot, you can use the wait command and monitor the status of the snapshot:

    1. Enter the following command:

      $ oc wait my-vm my-vmsnapshot --for condition=Ready
    2. Verify the status of the snapshot:

      • InProgress - The online snapshot operation is still in progress.

      • Succeeded - The online snapshot operation completed successfully.

      • Failed - The online snapshot operaton failed.

        Online snapshots have a default time deadline of five minutes (5m). If the snapshot does not complete successfully in five minutes, the status is set to failed. Afterwards, the file system will be thawed and the VM unfrozen but the status remains failed until you delete the failed snapshot image.

        To change the default time deadline, add the FailureDeadline attribute to the VM snapshot spec with the time designated in minutes (m) or in seconds (s) that you want to specify before the snapshot operation times out.

        To set no deadline, you can specify 0, though this is generally not recommended, as it can result in an unresponsive VM.

        If you do not specify a unit of time such as m or s, the default is seconds (s).

Verification
  1. Verify that the VirtualMachineSnapshot object is created and bound with VirtualMachineSnapshotContent. The readyToUse flag must be set to true.

    $ oc describe vmsnapshot <my-vmsnapshot>
    Example output
    apiVersion: snapshot.kubevirt.io/v1beta1
    kind: VirtualMachineSnapshot
    metadata:
      creationTimestamp: "2020-09-30T14:41:51Z"
      finalizers:
      - snapshot.kubevirt.io/vmsnapshot-protection
      generation: 5
      name: mysnap
      namespace: default
      resourceVersion: "3897"
      selfLink: /apis/snapshot.kubevirt.io/v1beta1/namespaces/default/virtualmachinesnapshots/my-vmsnapshot
      uid: 28eedf08-5d6a-42c1-969c-2eda58e2a78d
    spec:
      source:
        apiGroup: kubevirt.io
        kind: VirtualMachine
        name: my-vm
    status:
      conditions:
      - lastProbeTime: null
        lastTransitionTime: "2020-09-30T14:42:03Z"
        reason: Operation complete
        status: "False" (1)
        type: Progressing
      - lastProbeTime: null
        lastTransitionTime: "2020-09-30T14:42:03Z"
        reason: Operation complete
        status: "True" (2)
        type: Ready
      creationTime: "2020-09-30T14:42:03Z"
      readyToUse: true (3)
      sourceUID: 355897f3-73a0-4ec4-83d3-3c2df9486f4f
      virtualMachineSnapshotContentName: vmsnapshot-content-28eedf08-5d6a-42c1-969c-2eda58e2a78d (4)
    1 The status field of the Progressing condition specifies if the snapshot is still being created.
    2 The status field of the Ready condition specifies if the snapshot creation process is complete.
    3 Specifies if the snapshot is ready to be used.
    4 Specifies that the snapshot is bound to a VirtualMachineSnapshotContent object created by the snapshot controller.
  2. Check the spec:volumeBackups property of the VirtualMachineSnapshotContent resource to verify that the expected PVCs are included in the snapshot.

Verifying online snapshot creation with snapshot indications

Snapshot indications are contextual information about online virtual machine (VM) snapshot operations. Indications are not available for offline virtual machine (VM) snapshot operations. Indications are helpful in describing details about the online snapshot creation.

Prerequisites
  • To view indications, you must have attempted to create an online VM snapshot using the CLI or the web console.

Procedure
  1. Display the output from the snapshot indications by doing one of the following:

    • For snapshots created with the CLI, view indicator output in the VirtualMachineSnapshot object YAML, in the status field.

    • For snapshots created using the web console, click VirtualMachineSnapshot > Status in the Snapshot details screen.

  2. Verify the status of your online VM snapshot:

    • Online indicates that the VM was running during online snapshot creation.

    • NoGuestAgent indicates that the QEMU guest agent was not running during online snapshot creation. The QEMU guest agent could not be used to freeze and thaw the file system, either because the QEMU guest agent was not installed or running or due to another error.

Restoring a virtual machine from a snapshot in the web console

You can restore a virtual machine (VM) to a previous configuration represented by a snapshot in the web console.

Procedure
  1. Click VirtualizationVirtualMachines from the side menu.

  2. Select a virtual machine to open the VirtualMachine details page.

  3. If the virtual machine is running, click ActionsStop to power it down.

  4. Click the Snapshots tab. The page displays a list of snapshots associated with the virtual machine.

  5. Choose one of the following methods to restore a VM snapshot:

    1. For the snapshot that you want to use as the source to restore the VM, click Restore.

    2. Select a snapshot to open the Snapshot Details screen and click ActionsRestore VirtualMachineSnapshot.

  6. In the confirmation pop-up window, click Restore to restore the VM to its previous configuration represented by the snapshot.

Restoring a virtual machine from a snapshot in the CLI

You can restore an existing virtual machine (VM) to a previous configuration by using a VM snapshot. You can only restore from an offline VM snapshot.

Prerequisites
  • Install the OpenShift CLI (oc).

  • Power down the VM you want to restore to a previous state.

Procedure
  1. Create a YAML file to define a VirtualMachineRestore object that specifies the name of the VM you want to restore and the name of the snapshot to be used as the source.

    For example:

    apiVersion: snapshot.kubevirt.io/v1beta1
    kind: VirtualMachineRestore
    metadata:
      name: my-vmrestore (1)
    spec:
      target:
        apiGroup: kubevirt.io
        kind: VirtualMachine
        name: my-vm (2)
      virtualMachineSnapshotName: my-vmsnapshot (3)
    1 The name of the new VirtualMachineRestore object.
    2 The name of the target VM you want to restore.
    3 The name of the VirtualMachineSnapshot object to be used as the source.
  2. Create the VirtualMachineRestore resource. The snapshot controller updates the status fields of the VirtualMachineRestore object and replaces the existing VM configuration with the snapshot content.

    $ oc create -f <my-vmrestore>.yaml
Verification
  • Verify that the VM is restored to the previous state represented by the snapshot. The complete flag must be set to true.

    $ oc get vmrestore <my-vmrestore>
    Example output
    apiVersion: snapshot.kubevirt.io/v1beta1
    kind: VirtualMachineRestore
    metadata:
    creationTimestamp: "2020-09-30T14:46:27Z"
    generation: 5
    name: my-vmrestore
    namespace: default
    ownerReferences:
    - apiVersion: kubevirt.io/v1
      blockOwnerDeletion: true
      controller: true
      kind: VirtualMachine
      name: my-vm
      uid: 355897f3-73a0-4ec4-83d3-3c2df9486f4f
      resourceVersion: "5512"
      selfLink: /apis/snapshot.kubevirt.io/v1beta1/namespaces/default/virtualmachinerestores/my-vmrestore
      uid: 71c679a8-136e-46b0-b9b5-f57175a6a041
      spec:
        target:
          apiGroup: kubevirt.io
          kind: VirtualMachine
          name: my-vm
      virtualMachineSnapshotName: my-vmsnapshot
      status:
      complete: true (1)
      conditions:
      - lastProbeTime: null
      lastTransitionTime: "2020-09-30T14:46:28Z"
      reason: Operation complete
      status: "False" (2)
      type: Progressing
      - lastProbeTime: null
      lastTransitionTime: "2020-09-30T14:46:28Z"
      reason: Operation complete
      status: "True" (3)
      type: Ready
      deletedDataVolumes:
      - test-dv1
      restoreTime: "2020-09-30T14:46:28Z"
      restores:
      - dataVolumeName: restore-71c679a8-136e-46b0-b9b5-f57175a6a041-datavolumedisk1
      persistentVolumeClaim: restore-71c679a8-136e-46b0-b9b5-f57175a6a041-datavolumedisk1
      volumeName: datavolumedisk1
      volumeSnapshotName: vmsnapshot-28eedf08-5d6a-42c1-969c-2eda58e2a78d-volume-datavolumedisk1
    1 Specifies if the process of restoring the VM to the state represented by the snapshot is complete.
    2 The status field of the Progressing condition specifies if the VM is still being restored.
    3 The status field of the Ready condition specifies if the VM restoration process is complete.

Deleting a virtual machine snapshot in the web console

You can delete an existing virtual machine snapshot by using the web console.

Procedure
  1. Click VirtualizationVirtualMachines from the side menu.

  2. Select a virtual machine to open the VirtualMachine details page.

  3. Click the Snapshots tab. The page displays a list of snapshots associated with the virtual machine.

  4. Click the Options menu kebab of the virtual machine snapshot that you want to delete and select Delete VirtualMachineSnapshot.

  5. In the confirmation pop-up window, click Delete to delete the snapshot.

Deleting a virtual machine snapshot in the CLI

You can delete an existing virtual machine (VM) snapshot by deleting the appropriate VirtualMachineSnapshot object.

Prerequisites
  • Install the OpenShift CLI (oc).

Procedure
  • Delete the VirtualMachineSnapshot object. The snapshot controller deletes the VirtualMachineSnapshot along with the associated VirtualMachineSnapshotContent object.

    $ oc delete vmsnapshot <my-vmsnapshot>
Verification
  • Verify that the snapshot is deleted and no longer attached to this VM:

    $ oc get vmsnapshot

Additional resources