Migrating a VM between networks

This page describes how to migrate a VM instance from one network to another. In the case of a VM that is connected to more than one network using multiple network interfaces, this process updates one of the interfaces and leaves the rest in place.

The following migrations are supported:

From legacy network to a VPC network in the same project
From one VPC network to another VPC network in the same project
From one subnet of a VPC network to another subnet of the same network
From a service project network to the shared network of a Shared VPC host project

In all cases, the VM stays in the region and zone where it was before. Only the attached network changes.

Before you begin

Read the Virtual Private Cloud documentation.
If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Requirements

Before you move your VM, it must meet the following requirements:

The migration is a "cold" migration. The VM must be stopped before it can be migrated.
The VM must not be in an instance group or network endpoint group (NEG).
- If the VM is in an unmanaged instance group or NEG, you must take it out of the group before migrating it.
- VMs in managed instance groups cannot be migrated. Instead, you must copy your instance template to the new network and use it to rebuild the managed instance group.
- You can move instances in target pools without removing them first. The target pool expands to cover both networks.

Limitations

You cannot migrate a VM interface to a legacy network.
The MAC address allocated to the network interface will change during the migration. This could have an impact on services tightly coupled with MAC addresses such as third-party license agreement.
If you are migrating the VM to a network or subnet with a different IP range, the internal IP address of your instance must change. If you are migrating to a subnet with the same IP range, you can keep the old IP address, as long as it is not already in use at the destination, by specifying it during the migration.
If the target subnet does not have the same IP range as the source, then the IP address of the interface changes to match the new subnet range.
You can keep the VM's existing external IP address in the new location. To do this, you must have the compute.subnetworks.useExternalIp permission on the target network, and the target network cannot have external IP addresses disabled by the constraints/compute.vmExternalIpAccess constraint.

Migrating a VM

Before you migrate a VM, review the requirements and limitations.

Google recommends that you create any necessary firewall rules, routes, load balancers, and other network infrastructure resources in the new network before migrating your VMs. Doing so can shorten the time that your VMs are offline.

Console

In the Google Cloud console, go to the VM instances page.

Go to VM instances
Click the VM instance name to open the details page.
Click Stop .
If a confirmation dialog appears, click Stop.
After the VM stops, click Edit .
Under Network interfaces, click the interface you want to move.
In the Network field of the interface, select the new network for the interface.
In the Subnetwork field of the interface, select the new subnet for the interface.
In the Internal IP address field, specify Automatic if you want the system to allocate an IP address from the subnet range or Custom if you want to specify an unused one yourself.
Click Done to close the network interface edit panel.
Click Save.
After the VM finishes saving, click Start .
If a confirmation dialog appears, click Start.

gcloud

Stop the VM
```
gcloud compute instances stop INSTANCE_NAME \
    --zone=ZONE_NAME
```
where
- INSTANCE_NAME is the name of the VM instance.
- ZONE_NAME is the name of the zone containing the instance.
Migrate the VM
```
gcloud compute instances network-interfaces update INSTANCE_NAME \
    --zone=ZONE_NAME \
    --network-interface=NIC \
    --network=NETWORK_NAME \
    --subnetwork=SUBNET_NAME
```
where
- INSTANCE_NAME is the name of the VM instance.
- ZONE_NAME is the name of the zone containing the instance.
- NIC is the name of the interface you are updating. In a single-interface VM, the NIC is nic0.
- NETWORK_NAME is the target network name. If you are migrating the VM from a service project network to the host project network, you must use a fully qualified name for the target network: projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME
- SUBNET_NAME is the target subnet name. This subnet must be in the same region as the VM. If you are migrating the VM from a service project network to the host project network, you must use a fully qualified name for the subnet: projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
Start the VM

Migration might take a few minutes, so wait before trying to start the VM in the new location.
```
gcloud compute instances start INSTANCE_NAME \
    --zone=ZONE_NAME
```
where
- INSTANCE_NAME is the name of the VM instance.
- ZONE_NAME is the name of the zone containing the instance.

REST

Stop the VM
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_NAME/instances/INSTANCE_NAME/stop
```
where
- PROJECT_ID is your project ID.
- INSTANCE_NAME is the name of the VM instance.
- ZONE_NAME is the name of the zone containing the instance.
View details for the instance.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_NAME/instances/INSTANCE_NAME
```
where
- PROJECT_ID is your project ID.
- ZONE_NAME is the name of the zone containing the instance.
- INSTANCE_NAME is the name of the VM instance.
Find the fingerprint for the interface.

You need the fingerprint to update the network interface.

Examine the output of the command and find the networkInterfaces field contents. Find the item with the name of the interface you would like to update (in a single-interface VM, the name is nic0). Copy the string in the fingerprint field in this item for use in the next step.
Migrate the VM
```
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_NAME/instances/INSTANCE_NAME/updateNetworkInterface?networkInterface=NIC
{
  "network": NETWORK_NAME,
  "subnetwork": SUBNET_NAME,
  "networkIP": IP_ADDRESS,
  "name": NIC,
  "fingerprint": FINGERPRINT
}
```
- PROJECT_ID is your project ID.
- ZONE_NAME is the name of the zone containing the instance.
- INSTANCE_NAME is the name of the VM instance.
- NIC is the name of the interface you are updating. In a single-interface VM, the NIC is nic0.
- NETWORK_NAME is the target network name. If you are migrating the VM from a service project network to the host project network, you must use a fully qualified name for the target network: projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME
- SUBNET_NAME is the target subnet name. This subnet must be in the same region as the VM. If you are migrating the VM from a service project network to the host project network, you must use a fully qualified name for the subnet: projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
- IP_ADDRESS is the internal IP address you want the instance to have in the new location. If you omit this field, the interface is assigned one automatically.
- FINGERPRINT is the fingerprint you got in the previous step.
Start the VM
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_NAME/instances/INSTANCE_NAME/start
```
where
- PROJECT_ID is your project ID.
- INSTANCE_NAME is the name of the VM instance.
- ZONE_NAME is the name of the zone containing the instance.

What's next

Learn how to move an instance to another zone.
Learn about live migration.
Check a VM's status.