Skip to main content
Version: 2.8

Preserve Static IP and MAC address for VM restore

Overview​

This enhancement enables Portworx Backup to handle specific operational behaviors during the backup and restore of KubeVirt VirtualMachine (VM) objects by utilizing custom annotations. These annotations allow users to control whether the VM should start on restore and whether its MAC address should be masked.

Applicable To

  1. Platform: Kubernetes with KubeVirt

  2. Portworx Backup Version: 2.8.4 and above

Supported Annotations

  • px-backup/skip-vm-start: prevents the VM from starting automatically when restored
  • px-backup/skip-mac-masking: skips masking of the VM's MAC address during backup/restore

With Kubectl edit command​

Usage Instructions

  1. Edit the VirtualMachine resource using the following command before taking the VM backup (single or multi-VM backup):

    kubectl edit vm <vm-name> -n <vm-namespace>

  2. Add or update the annotations under the metadata.annotations section:

    apiVersion: kubevirt.io/v1
    kind: VirtualMachine
    metadata:
      annotations:
        px-backup/skip-vm-start: ""
        px-backup/skip-mac-masking: ""

    Value of these two annotations (key) can be empty or any random string.

  3. Save and exit the editor to apply the changes.

Behavior on Restore

  1. When px-backup/skip-vm-start is present, the VM remains in the stopped state after restore. This allows users to perform post-restore inspection or configuration before starting the VM.

  2. When px-backup/skip-mac-masking is present, Portworx Backup retains the original MAC address of the VM. Use this if MAC address consistency is critical for your application or licensing.

    1. Restoring VMs with this annotation is only possible if the specified MAC address is not already in use by another VM in that cluster.

Considerations

These annotations must be present at the time the VM is backed up.

If both annotations are omitted, the VM will be started automatically after restore and MAC masking will be applied.

Example:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: my-kubevirt-vm
  namespace: my-namespace
  annotations:

With kubectl patch command​

Alternatively you can also add or update metadata annotations on KubeVirt VirtualMachine resources using the kubectl patch command. Specific annotations—like px-backup/skip-mac-masking can control how VMs are handled during backup and restore operations. This method is useful for scripting, automation, or making quick updates without manually editing the full VM manifest.

Skipping MAC Address Masking

Portworx Backup automatically masks the MAC address of a KubeVirt VM when backing it up. This helps avoid MAC conflicts on restore. However, in certain scenarios, users may want to retain the original MAC address, such as when applications are bound to static MACs or licensed by hardware ID.

To prevent MAC address masking, use the following annotation:

  • px-backup/skip-mac-masking

Command Syntax

kubectl patch vm <vm-name> -n <namespace> \
  --type=merge \
  -p '{"metadata": {"annotations": {"px-backup/skip-mac-masking": ""}}}'

Example

kubectl patch vm vm-multi-disk -n lin-vm-2disk-repl3 \
  --type=merge \
  -p '{"metadata": {"annotations": {"px-backup/skip-mac-masking": ""}}}'

Output

virtualmachine.kubevirt.io/vm-multi-disk patched

Result

This command applies the px-backup/skip-mac-masking annotation to the VM named vm-multi-disk in the lin-vm-2disk-repl3 namespace. The annotation instructs Portworx Backup to retain the original MAC address of the VM during backup and restore.

note
  • This command does not restart or otherwise modify the state of the VM.
  • You can verify the annotation by running: kubectl get vm <vm-name> -n <namespace> -o yaml

Additional Annotations

You can use similar kubectl patch commands to apply other supported annotations, such as:

kubectl patch vm <vm-name> -n <namespace> \
  --type=merge \
  -p '{"metadata": {"annotations": {"px-backup/skip-vm-start": ""}}}'

Related topics:

Last updated on