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

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

  1. In the Cloud Console, go to the VM instances page.

    Go to VM instances

  2. Click the VM instance name to open the details page.

  3. Click Stop .

  4. If a confirmation dialog appears, click Stop.

  5. After the VM stops, click Edit .

  6. Under Network interfaces, click the interface you want to move.

  7. In the Network field of the interface, select the new network for the interface.

  8. In the Subnetwork field of the interface, select the new subnet for the interface.

  9. 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.

  10. Click Done to close the network interface edit panel.

  11. Click Save.

  12. After the VM finishes saving, click Start .

  13. If a confirmation dialog appears, click Start.

gcloud

  1. Stop the VM

    gcloud beta 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.
  2. Migrate the VM

    gcloud beta 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
  3. Start the VM

    Migration might take a few minutes, so wait before trying to start the VM in the new location.

    gcloud beta 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.

API

  1. Stop the VM

    POST https://compute.googleapis.com/compute/beta/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.
  2. Get the fingerprint for the interface.

    You need the fingerprint to update the network interface.

    GET https://www.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE_NAME/instances/INSTANCE_NAME/updateNetworkInterface?networkInterface=NIC
    

    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.
    • NIC is the name of the interface you are updating. In a single-interface VM, the NIC is nic0.

    Copy the string in the fingerprint field for use in the next step.

  3. Migrate the VM

    PATCH https://www.googleapis.com/compute/beta/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 copied in from the GET command.
  4. Start the VM

    POST https://compute.googleapis.com/compute/beta/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