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 multiplenetwork interfaces, this process updates one of the interfaces and leaves therest 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 networkin the same project
- From one subnet of a VPC network to another subnet of thesame network
- From a service project network to the shared network of a Shared VPChost project
In all cases, the VM stays in the region and zone where it was before. Onlythe attached network changes.
Before you begin
- Read theVirtual Private Cloud documentation.
- If you haven't already, set upauthentication. Authentication verifies your identity 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
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- 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.
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.
Requirements
Before you migrate a VM, it must meet the following requirements:
- The VM uses only IPv4 addresses.
- The VM must be stopped. To ensure that the guest OS in the VM can cleanly shutdown before the stop operation completes, you can optionallyenable graceful shutdown in the VM.
- The VM mustn't be part of an instance group or a network endpoint group (NEG).The following conditions apply:
- If the VM is part of an unmanaged instance group or NEG, then you mustremove the VM from the group before migrating it.
- If the VM is part of a managed instance group (MIG), then the VM can't bemigrated. Instead, create a new MIG using an instance template withdifferent VM properties.
- You can move instances in target pools without removing them first. Thetarget 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 themigration. This could have an impact on services tightly coupled with MACaddresses 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 migratingto a subnet with the same IP range, you can keep the old IP address, as longas it is not already in use at the destination, by specifying it during themigration.
- If the target subnet does not have the same IP range as the source, thenthe 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 dothis, you must have the
compute.subnetworks.useExternalIppermission on the target network, and the target network cannot have externalIP addresses disabled by theconstraints/compute.vmExternalIpAccessconstraint.
Migrating a VM
Before you migrate a VM, review therequirements andlimitations.
Google recommends that you create any necessary firewallrules, routes, load balancers, and other network infrastructure resources inthe new network before migrating your VMs. Doing so can shorten the time thatyour VMs are offline.
Important: Migrating a VM can take several minutes. After you start migrating aVM, don't interrupt the process or modify any resources thatCompute Engine is migrating.To migrate a VM, select one of the following options:
Console
In the Google Cloud console, go to theVM instances page.
Click the VM instance name to open the details page.
If the VM is running, clickStop to stop the VM. If there is noStop option, clickMore actions >Stop.
After the VM stops, clickEdit.
UnderNetwork interfaces, click the interface you want to move.
In theNetwork field of the interface, select the new network forthe interface.
In theSubnetwork field of the interface, select the new subnet forthe interface.
In theInternal IP address field, specifyAutomatic if you wantthe system to allocate an IP address from the subnet range orCustomif you want to specify an unused one yourself.
ClickDone to close the network interface edit panel.
ClickSave.
After the VM finishes saving, clickStart.
If a confirmation dialog appears, clickStart.
gcloud
Stop the VM
gcloud compute instances stopINSTANCE_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 updateINSTANCE_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 asingle-interface VM, theNIC is
nic0. - NETWORK_NAME is the target network name. If you aremigrating the VM from a service project network to the host projectnetwork, 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 subnetmust be in the same region as the VM. If you are migrating the VMfrom a service project network to the host project network, you mustuse 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 startthe VM in the new location.
gcloud compute instances startINSTANCE_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
networkInterfacesfieldcontents. Find the item with the name of the interface you would like toupdate (in a single-interface VM, the name isnic0). Copy the stringin thefingerprintfield 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 asingle-interface VM, theNIC is
nic0. - NETWORK_NAME is the target network name. If you aremigrating the VM from a service project network to the host projectnetwork, 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 subnetmust be in the same region as the VM. If you are migrating the VMfrom a service project network to the host project network, you mustuse 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 theinstance 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 tomove an instance to another zone.
- Learn aboutlive migration.
- Check a VM'sstatus.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.