Repository: harvester/docs
Pull request #721: Add network config suggestions for VM running Ubuntu
Author: login: mingshuoqiu
Created: 2025-03-03T11:20:09Z | Merged: 2025-03-13T09:14:18Z

Related to https://github.com/harvester/harvester/issues/4474


Diff:
diff --git a/docs/vm/backup-restore.md b/docs/vm/backup-restore.md
index 1da6c367bb3..1f235b6eb54 100644
--- a/docs/vm/backup-restore.md
+++ b/docs/vm/backup-restore.md
@@ -58,6 +58,24 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+The network configuration of a virtual machine running an Ubuntu release later than 16.04 is likely managed by `netplan` by default. Before creating backups, you must stop the virtual machine, edit the configuration (**Edit Config > Advanced Options**), and then restart the virtual machine. Use the following `network` settings as reference for DHCP configuration.
+
+```YAML
+network:
+  ethernets:
+    enp1s0:
+      dhcp4: true
+      dhcp6: true
+      dhcp-identifier: mac
+  version: 2
+```
+
+The restored virtual machine retains the machine ID of the original virtual machine. If `dhcp-identifier: mac` is not specified, the restored virtual machine receives the same IP address from the DHCP server because `netplan` uses the machine ID as the DHCP client identifier by default. This is why you must configure the `network` settings before creating backups of virtual machines running Ubuntu. Failure to do so may result in unexpected behavior and potential network conflicts.
+
+:::
+
 ### Restore a new VM using a backup
 
 To restore a new VM from a backup, follow these steps:
@@ -150,6 +168,24 @@ The `State` will be set to `Ready` once the snapshot is complete.
 
 Users can either restore a new VM or replace an existing VM using this snapshot.
 
+:::note
+
+The network configuration of a virtual machine running an Ubuntu release later than 16.04 is likely managed by `netplan` by default. Before creating snapshots, you must stop the virtual machine, edit the configuration (**Edit Config > Advanced Options**), and then restart the virtual machine. Use the following `network` settings as reference for DHCP configuration.
+
+```YAML
+network:
+  ethernets:
+    enp1s0:
+      dhcp4: true
+      dhcp6: true
+      dhcp-identifier: mac
+  version: 2
+```
+
+The restored virtual machine retains the machine ID of the original virtual machine. If `dhcp-identifier: mac` is not specified, the restored virtual machine receives the same IP address from the DHCP server because `netplan` uses the machine ID as the DHCP client identifier by default. This is why you must configure the `network` settings before creating snapshot of virtual machines running Ubuntu. Failure to do so may result in unexpected behavior and potential network conflicts.
+
+:::
+
 ### Restore a new VM using a snapshot
 
 To restore a new VM from a snapshot, follow these steps:
diff --git a/docs/vm/create-vm.md b/docs/vm/create-vm.md
index 31bb8d2f7f0..a7aeeb74b76 100644
--- a/docs/vm/create-vm.md
+++ b/docs/vm/create-vm.md
@@ -297,6 +297,24 @@ network:
 
 You can also use the `Advanced > Cloud Config Templates` feature to create a pre-defined cloud-init configuration template for the VM.
 
+:::note
+
+The network configuration of a virtual machine running an Ubuntu release later than 16.04 is likely managed by `netplan` by default. Please use the following `network` settings as reference for DHCP configuration to prevent IP address conflicts when restoring a virtual machine from a snapshot or backup.
+
+```YAML
+network:
+  ethernets:
+    enp1s0:
+      dhcp4: true
+      dhcp6: true
+      dhcp-identifier: mac
+  version: 2
+```
+
+If dhcp-identifier: mac is not specified, the restored virtual machine will receive the same IP address from the DHCP server. This happens because netplan defaults to using the machine ID as the DHCP client identifier. As a result, the restored virtual machine will receive the same IP address from the DHCP server and lead to IP address conflicts.
+
+:::
+
 #### Installing the QEMU guest agent
 The QEMU guest agent is a daemon that runs on the virtual machine instance and passes information to the host about the VM, users, file systems, and secondary networks.
 


Reviews:
user: login: w13915984028
body: LGTM, thanks.
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-04T07:57:39Z
user: login: starbops
body: LGTM, thank you.
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-04T08:23:54Z
user: login: mingshuoqiu
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-05T04:22:25Z
user: login: mingshuoqiu
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-05T04:25:25Z
user: login: jillian-maroket
body: Review done
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-05T09:01:59Z
user: login: jillian-maroket
body: Thanks!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-12T06:16:09Z
user: login: innobead
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-13T09:14:13Z

Review comments:
diff_hunk: @@ -58,6 +58,22 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+If your OS is Ubuntu and the version is newer than 16.04, the network configuration is very likely handled by `netplan` by default. Please `Edit Config` > `Advanced Options` on your VM before creating backup, and take the following network-data as reference for DHCP configuration.
path: docs/vm/backup-restore.md
user: login: w13915984028
body: Edit config means the VM needs to be restarted in general.

Add this hint to `vm creation` page too?
created_at: 2025-03-04T07:55:36Z
author_association: MEMBER
diff_hunk: @@ -58,6 +58,22 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+If your OS is Ubuntu and the version is newer than 16.04, the network configuration is very likely handled by `netplan` by default. Please `Edit Config` > `Advanced Options` on your VM before creating backup, and take the following network-data as reference for DHCP configuration.
+```YAML
+network:
+  ethernets:
+    enp1s0:
+      dhcp4: true
+      dhcp6: true
+      dhcp-identifier: mac
+  version: 2
+```
+The restored VM will retain the same machine ID as the original, which will cause it to receive the same IP address from the DHCP server if `dhcp-identifier: mac` is not specified since `netplan` use machine ID as dhcp identifier by default. It is essential to configure the network-data before performing a VM backup for Ubuntu systems. Failure to do so will result in unexpected behavior and potential network conflicts.
path: docs/vm/backup-restore.md
user: login: w13915984028
body: A further question, is it possbile to mutator the VM to change `dhcp-identifier` when restoring? That will benefits all users.
created_at: 2025-03-04T07:57:14Z
author_association: MEMBER
diff_hunk: @@ -58,6 +58,22 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+If your OS is Ubuntu and the version is newer than 16.04, the network configuration is very likely handled by `netplan` by default. Please `Edit Config` > `Advanced Options` on your VM before creating backup, and take the following network-data as reference for DHCP configuration.
path: docs/vm/backup-restore.md
user: login: mingshuoqiu
body: Yup. The VM needs to be stopped before `Edit Config`. I'll add to the `vm creation`.
created_at: 2025-03-05T04:22:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -58,6 +58,22 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+If your OS is Ubuntu and the version is newer than 16.04, the network configuration is very likely handled by `netplan` by default. Please `Edit Config` > `Advanced Options` on your VM before creating backup, and take the following network-data as reference for DHCP configuration.
+```YAML
+network:
+  ethernets:
+    enp1s0:
+      dhcp4: true
+      dhcp6: true
+      dhcp-identifier: mac
+  version: 2
+```
+The restored VM will retain the same machine ID as the original, which will cause it to receive the same IP address from the DHCP server if `dhcp-identifier: mac` is not specified since `netplan` use machine ID as dhcp identifier by default. It is essential to configure the network-data before performing a VM backup for Ubuntu systems. Failure to do so will result in unexpected behavior and potential network conflicts.
path: docs/vm/backup-restore.md
user: login: mingshuoqiu
body: I tried w/o luck. They will need to modify the netplan config and do `netplan apply`
created_at: 2025-03-05T04:25:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -58,6 +58,22 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+If your OS is Ubuntu and the version is newer than 16.04, the network configuration is very likely handled by `netplan` by default. Please `Edit Config` > `Advanced Options` on your VM before creating backup, and take the following network-data as reference for DHCP configuration.
path: docs/vm/backup-restore.md
user: login: jillian-maroket
body: ```suggestion
The network configuration of a virtual machine running an Ubuntu release later than 16.04 is likely managed by `netplan` by default. Before creating backups, you must stop the virtual machine, edit the configuration (**Edit Config > Advanced Options**), and then restart the virtual machine. Use the following `network` settings as reference for DHCP configuration.
```
created_at: 2025-03-05T08:59:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -58,6 +58,22 @@ The `State` will be set to `Ready` once the backup is complete.
 
 Users can either restore a new VM or replace an existing VM using this backup.
 
+:::note
+
+If your OS is Ubuntu and the version is newer than 16.04, the network configuration is very likely handled by `netplan` by default. Please `Edit Config` > `Advanced Options` on your VM before creating backup, and take the following network-data as reference for DHCP configuration.
+```YAML
+network:
+  ethernets:
+    enp1s0:
+      dhcp4: true
+      dhcp6: true
+      dhcp-identifier: mac
+  version: 2
+```
+The restored VM will retain the same machine ID as the original, which will cause it to receive the same IP address from the DHCP server if `dhcp-identifier: mac` is not specified since `netplan` use machine ID as dhcp identifier by default. It is essential to configure the network-data before performing a VM backup for Ubuntu systems. Failure to do so will result in unexpected behavior and potential network conflicts.
path: docs/vm/backup-restore.md
user: login: jillian-maroket
body: ```suggestion
The restored virtual machine retains the machine ID of the original virtual machine. If `dhcp-identifier: mac` is not specified, the restored virtual machine receives the same IP address from the DHCP server because `netplan` uses the machine ID as the DHCP client identifier by default. This is why you must configure the `network` settings before creating backups of virtual machines running Ubuntu. Failure to do so may result in unexpected behavior and potential network conflicts.
```
created_at: 2025-03-05T09:01:26Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-03-03T11:39:17Z
body: <!-- deploy-comment -->

|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | a74b6e721548bf9d5ea784b05a1b7acfaec2753c |
|<span aria-hidden="true">😎</span> Deploy Preview | https://67d1203ecce1f00a72e97ceb--harvester-preview.netlify.app |

author_association: NONE
user: login: mingshuoqiu
created_at: 2025-03-12T05:32:05Z
body: Thanks. I revised the backup-restore part per the suggestion and add the same in create-vm.
author_association: CONTRIBUTOR