Skip to main content
Version: 3.2

Preserve Static IP and MAC address for VM Backup and Restore

Applicable to Classic mode only

Overview​

Portworx Backup can preserve a KubeVirt VirtualMachine (VM)'s network identity across backup and restore, and can control whether a VM starts automatically after restore. By default, Portworx Backup masks a VM's MAC address during backup to avoid conflicts when the VM is restored. However, many KubeVirt VMs bind their static IP address to their MAC address, so masking the MAC address causes the VM to lose its original static IP on restore.

Starting with Portworx Backup 2.11.0, you control this behavior directly in the restore wizard using the VM options, rather than by annotating the VM. The annotation-based method is retained only for backward compatibility; see Annotation-based method (legacy).

Applicable To

  1. Platform: Kubernetes with KubeVirt

  2. Portworx Backup Version: 2.11.0 and later (restore wizard VM options)

Prerequisites​

  • KubeVirt is installed on both the source and destination clusters.
  • The source and destination clusters meet the KubeVirt VM backup prerequisites, including the required KubeVirt and Stork versions. For more information, see Virtual Machine backups.

When you restore a VM backup, select the following VM options in the restore wizard:

  • Skip MAC address masking: retains the VM's original MAC address instead of masking it, which preserves any static IP that is bound to that MAC address. Use this when MAC address consistency is critical, for example when an application is bound to a static MAC or is licensed by hardware ID.
  • Skip virtual machine restart after restore: leaves the VM in the stopped state after restore, so that you can inspect or configure it before you start it.

If you do not select either option, the VM starts automatically after restore and its MAC address is masked. For where these options appear in the restore flow, see Restore a VM Backup.

Behavior when retaining the MAC address​

  1. Restoring a VM with its original MAC address succeeds only if that MAC address is not already in use by another VM in the destination cluster. If the MAC address is already in use, that VM cannot be restored with its original MAC address, and the restore of that VM fails. In this case, restore the VM without Skip MAC address masking so that Portworx Backup assigns a new MAC address.

  2. In a multi-VM restore, if one VM fails because of a MAC address conflict, only that VM fails. The remaining VMs can still be restored, and the overall restore is reported as Partial Success. For more information, see Partial Success in VM Restores.

Annotation-based method (legacy)​

note

The annotation-based method described in this section is a legacy approach that predates the restore wizard VM options. Use the restore options described in Restore options (recommended) instead. Portworx Backup continues to honor these annotations on previously backed-up VMs for backward compatibility.

Unlike the restore options, which you select at restore time, these annotations must be present on the VM at the time the backup is taken:

  • px-backup/skip-vm-start: prevents the VM from starting automatically when it is restored.
  • px-backup/skip-mac-masking: retains the VM's original MAC address instead of masking it.

With the 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: ""

    The value of these two annotation keys can be empty or any string.

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

Behavior on Restore

  • When px-backup/skip-vm-start is present, the VM remains in the stopped state after restore.
  • When px-backup/skip-mac-masking is present, Portworx Backup retains the original MAC address of the VM. The MAC-address conflict behavior is the same as for the restore wizard option; see Behavior when retaining the MAC address.
  • If both annotations are omitted, the VM starts automatically after restore and its MAC address is masked.

These annotations must be present on the VM at the time the backup is taken.

Example:

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

With the kubectl patch command​

Alternatively, you can 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 <vm-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 <vm-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 <vm-namespace> \
--type=merge \
-p '{"metadata": {"annotations": {"px-backup/skip-vm-start": ""}}}'

Related topics:

In this topic: