Legacy networks are not recommended and can no longer be created. Many newer Google Cloudfeatures are not supported in legacy networks. Instead, useVirtual Private Cloud (VPC) networks. For more information aboutreplacing legacy networks, see Replace legacy networks.
This page describes modifying Google Cloud legacynetworks. Use this page only if you have an existingsetup that has a legacy network.
Restrictions
Legacy networks do not support the following Google Cloud features. To usethese features, you must use VPC networksinstead.
- VPC subnets
- Alias IP
- Multiple network interfaces
- Shared VPC
- VPC Network Peering
- All private access options for services
Single-region legacy networks can be converted into VPC networksusing Convert a single region to a VPCnetwork. If you have multi-regional legacynetworks, you must migrate resources to a single region before you use theconversion tool.
Create a legacy network
You can no longer create a legacy network.
If you try to create a legacy network, this error is displayed:
Creation of legacy mode networks is deprecated. Please create a subnet modenetwork instead by removing the IPv4Range field and adding theautoCreateSubnetworks field to your network insert request.
Migrate VMs out of a legacy network
You can migrate your virtual machine (VM) instances out of your legacy networkto a VPC network. For instructions, seeMigrating a VM betweennetworks.
Delete a legacy network
For a legacy network, you can explicitly delete the network only ifthe network is not in use by any resources.
To delete the network:
gcloud compute networks delete LEGACY_NETWORK_NAME
Replace the following:
LEGACY_NETWORK_NAME: the name of the legacy network thatyou want to delete.
Convert a single-region legacy network to a VPC network
You can use the single-region conversion tool to convert a legacy network to acustom mode VPC network in the same project. All resources inthe legacy network must be located in a single region. See Single-regionconversion details for moreinformation.
Limitations of the single-region conversion tool
After the conversion has started, it cannot be canceled.
All resources must exist in a single region before you can convert a legacynetwork to a VPC network. If you have resources in multipleregions, the conversion fails and Google Cloud takes no action. You mustmanually move resourcesto a single region or remove them from regions other than the one you'remigrating. You can't, for example, convert resources region by region intomultiple VPC networks.
During the conversion, the network continues to pass traffic, and communicationis not interrupted. However, changes to network resources are limited. Networkresources can be deleted, but certain deletions are blocked until the conversionis complete. Network resources cannot be created during the conversion.
You can't revert a converted VPC network back to a legacynetwork.
If your legacy network contains Google Kubernetes Engine clusters, yourGKE clusters must be upgraded after you convert the legacynetwork to ensure that components operate correctly. For more information, seeConverting a legacy network that contains GKE clusters.
Prepare to convert a legacy network
Consider performing the conversion when user activity on the network is low.
To use the conversion too, all resources in the legacy network must be in oneregion. If you have resources in multiple regions, decide which regionyou want to use, and move yourinstances to that region.Other resources not in that region must be manually moved or deleted.
Ensure the last two internal IP addresses in the network CIDR range are notin use. These IP addresses are unusableaddresses inVPC network subnets.
For example, for a network with an IP address range of
10.240.0.0/16, verifythat10.240.255.254and10.240.255.255are not assigned to any resources.Manually scale up any instance groups to cover any expected need during theconversion and disableautoscalers.
If an autoscaler is enabled during the conversion, and the autoscaler attemptsto create a new instance, you might see anerror.
If your legacy network contains GKE clusters, see Convertinga legacy network that contains GKE clusters.
Convert a legacy network
Using the tool to convert from a legacy network to a VPC networkdoes not disrupt network traffic; your resources continue to operate normally.If the network conversion fails for any reason, the network conversion isautomatically rolled back. If you run into errors, see thetroubleshooting section for solutions.
Convert the legacy network to a VPC network.
The conversion is a long-running operation. The time it takes depends on thenumber of resources on the network. Converting a network takes at leastseven minutes to complete. Large networks can take over 20 minutes per 1,000VMs. During the conversion, no changes to the network are allowed.
gcloud
gcloud beta compute networks update LEGACY_NETWORK_NAME \ --switch-to-custom-subnet-mode
Replace the following:
LEGACY_NETWORK_NAME: the name of the legacy networkthat you want to convert.
API
POST https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/networks/LEGACY_NETWORK_NAME/switchToCustomMode
Replace the following:
PROJECT_ID: the project that contains the legacynetwork that you want to convert.LEGACY_NETWORK_NAME: the name of the legacy networkthat you want to convert.
You can monitor the status of the operation using theglobalOperations.getmethod or theglobalOperations.waitmethod.
After the operation is complete, check that the network's subnet mode is
CUSTOM.List your networks to see their subnet mode:
gcloud compute networks list
If you previously disabled any autoscalers,re-enable theautoscalers.
In the VPC network, addsubnets in the regions where you want tocreate new resources.
Recreate any resources that weren't included in the conversion.
Convert a legacy network that contains GKE clusters
If your legacy network contains GKE clusters, yourGKE clusters must be upgraded after the conversion to ensurethat components operate correctly.
Use the GKE networkconversion script to perform network, cluster, and node pool upgrades.
If you have converted a legacy network to aVPC network without using the script, you can use the script tomake the necessary cluster and node pool upgrades.
Update resources after a single-region conversion
Legacy networks do not have subnetworks, so any scripts or commands used tocreate or modify resources on a legacy network do not specify a subnetwork.VPC networks do contain subnetworks; therefore, scripts andcommands that manage resources in VPC networks normally requirethat you specify a subnetwork.
However, to ensure scripts and commands that were used to manage the legacynetwork still work after converting to a VPC network, thefollowing applies:
If you run a gcloud CLI command or make an API request thatspecifies the same region that the legacy network was using at the time of theconversion, the subnetwork is automatically set to the subnetwork that wascreated during the conversion operation.
If you run a gcloud CLI command or make an API request thatspecifies a different region from the region that the legacy network was usingat the time of the conversion, you must specify a subnetwork.
Troubleshooting a single-region conversion
Conversion attempt: Cannot convert network with VMs in multiple regions
When you try to convert my network, you get this error:
ERROR: (gcloud.compute.networks.switchToCustomMode) ResponseError: code=400, message=Only single-region legacy networks are supported. This network has at least one resource in us-central1 and at least one resource in asia-east1.
Solution:Converting the mode of a network from legacy to custom mode only works when allof these resources exist in a single region:
- instances, including stopped instances
- instance group
- managed instance groups
- forwarding rules
- routers
To proceed, either migrate all resources to one region or delete them beforeconverting.
Conversion attempt: Cannot convert network due to rate limit exceeded
When you try to convert my network, you get this error:
Error 403: Rate Limit Exceeded, rateLimitExceeded
Solution:The conversion operation has a global quota for concurrent operations. If yousee this error, wait five minutes and try again.
During conversion: Cannot create VMs in a network that is switching mode
When you try to create, delete or update VMs, you get this error:
ERROR: (gcloud.compute.instances.create) ResponseError: code=400, message="Resource not ready".
Solution:Switching the mode of a network locks down the network so that no new VMs canbe created in it until the operation is complete. You can create, delete, andupdate VMs after the conversion is complete.
After conversion: Cannot create resources without specifying subnetwork
When you try to create new resources on the network, you get this error:
gERROR: (gcloud.compute.instances.create) ResponseError: code=400, message=Subnetwork should be specified for custom subnetmode network.
Solution:Update resource creation scripts to specify the subnetwork of the resource.
After conversion: Cannot delete subnetwork
When you try to delete the converted network, or the subnetwork that was createdduring the conversion operation, you get this error:
ERROR: (gcloud.compute.networks.subnets.delete) Could not fetch resource: - Cannot delete subnetwork created during legacy network to custom-mode conversion for a day. Please try again tomorrow.
Solution:Wait for a day, then try deleting the network or subnetwork.
Manually migrate to a VPC network
In cases where you can't do a single-region conversion, you can recreate allresources in your legacy network in a VPC network. There is noautomated solution to convert multiple regions in a legacy network to aVPC network.
Create a custom mode VPC network, andthen add a subnet in every region that you're using.
In your legacy network, record the details of your existing resources. Youneed this information so that you can recreate them in the VPCnetwork.
To help you get started, the following items are some common resources thatyou might need to recreate.
- Cloud Routers
- Load balancers
- VPC firewall rules
- Instance templates
- Routes
- VM instances
- VPN gateways
- Protocol forwarding
Recreate your resources with the same configurations that you recorded. Someresources, like VM instances, require additional planning and steps torecreate. For some examples, see the Specialconsiderations section.
If possible, recreate your resources before removing the existing ones. Thatway, you can test and verify that the new resources operate as expectedbefore you remove the existing ones. Recreating might not be possible forall resources; you might exceed a quota or might not be able to reuse anexisting naming convention.
Delete your old resources and legacy network.
Special considerations for manual migration
Simply recreating resources can result in disruptions to your services. To avoiddisruptions, you might need to take additional actions before you migrate. Forexample, you might need to duplicate your service's infrastructure so that youcan redirect traffic from the old network to the new one. Or, you might need totake snapshots of existing VM instances to preserve and move their data to newinstances.
The following scenarios are examples that you might want to plan for beforeyou migrate:
- If you're using an ephemeral external IP address and you want to keep usingit, promote it to a reserved static IPaddress.
- If you need to move VM instances, you can manually recreatethem,or use Google Cloud to create a similarinstance from anexisting one. If you create a similar instance, Google Cloud doesn'tcopy existing data, but you can usesnapshots and bootdisks to do that.
- If you have a load balanced service and want to keep it running, add aduplicate backend in the VPC network. You can start directingtraffic to the backend in the VPC before you remove thebackend in the legacy network.
What's next
- For information about routes, see Routes.
- For information about firewall rules, see VPC firewall rules.
