Migrate an ECS instance to a different VPC within the same region and zone for network isolation, architecture redesign, or IP conflict resolution.
Changing the VPC for an ECS instance causes a temporary service interruption. Perform this operation during off-peak hours. Before you start, create a snapshot to back up your data.
Potential impacts
Service interruption: The operation requires the instance to be in the Stopped state, which interrupts services.
Private IP address change:
The primary private IP address changes to a new address from the destination vSwitch CIDR block. You can specify the address or let the system assign one. Applications with the original IP hard-coded, such as database connection strings, firewall whitelists, or other service configurations, will fail. Update these configurations after changing the VPC.
The public IP address remains unchanged.
Network connection lost: The instance loses private network connectivity to all resources in the original VPC, such as RDS instances, SLB instances, and other ECS instances.
Operating system network configuration: If the OS uses a static IP address, its network settings (IP address, gateway) will not match the new environment after the VPC change, preventing network communication and remote connection.
Procedure
Step 1: Prepare
Create a snapshot backup: Create a snapshot of the instance's system disk and data disks for backup and rollback.
Stop the instance
The instance must be in the Stopped state. The console status cannot be Locked. If the instance is running, stop it.
Perform prerequisite checks:
Secondary ENIs: Detach all secondary ENIs from the instance.
Multiple IP addresses: Unassign secondary private IP addresses and delete IPv6 addresses from the primary ENI.
Server Load Balancer (SLB): Remove the instance from any SLB backend server group.
Custom route entries: Delete any custom routes that use the instance as the next hop.
High-availability virtual IP address (HaVip): Dissociate the instance from any HaVip.
Global Accelerator (GA): Delete the endpoint that contains the instance from any GA instance.
(Optional) IP address acquisition method: If the instance's OS uses a static IP configuration, switch to DHCP before changing the VPC so the OS automatically retrieves the new IP address, subnet mask, and gateway.
Linux
Windows
The following steps use Windows Server 2022 as an example:
-
Connect to the Windows instance.
For instructions, see Connect to a Windows instance by using Workbench.
-
Open the Network and Sharing Center.
-
Click change adapter settings.
-
Double-click the primary network interface, Ethernet. In the Ethernet Status dialog box, click Type.
-
In the Ethernet Properties dialog box, double-click Internet Protocol Version 4 (TCP/IPv4).
In the Internet Protocol Version 4 (TCP/IPv4) Properties dialog box, select Obtain An IP Address Automatically.
-
Prepare destination network resources:
VPC and vSwitch: Ensure a VPC and vSwitch exist in the same zone as the instance.
Security group: Prepare a security group in the destination VPC. You can clone a security group to copy existing rules.
Step 2: Change the VPC
Console
Go to the ECS console. Select the resource group and region of the instance.
On the Instances page, click the instance ID to open its details page. Choose All Operations > Change VPC.
Change the VPC:
Preparation: Review the network information and notes.
VPC: Set Destination VPC, Destination vSwitch, and Destination Security Group.
You can select one to five destination security groups. The selected security groups must be of the same type: either all basic security groups or all enterprise security groups.
(Optional) Configure Primary Private IP: Specify a primary private IP address within the destination vSwitch CIDR block. If left empty, the system assigns one automatically.
Verify the results:
On the Instance Details page, check the new VPC and vSwitch in the Configuration Information section.
After the VPC is changed, the instance does not automatically start. You must manually start the instance.
API
Call ModifyInstanceVpcAttribute to change the VPC.
Call DescribeInstances to verify the new VPC, vSwitch, and security group.
The instance does not start automatically after the VPC change. Call StartInstance to start it.
FAQ
How do I change the VPCs for multiple ECS instances in a batch?
See Perform batch operations on the Instances page. You can change the VPCs for up to 20 instances at a time.
How do I convert a CIDR block to an IP address range?
See Examples of converting CIDR blocks to IP address ranges. You can also use the
ipcalccommand-line interface on an instance in the destination vSwitch to view the IP address range of a CIDR block.How do I subscribe to event notifications for the results of a VPC change operation?
Subscribe to ECS system events through CloudMonitor. After you subscribe to ECS system event notifications, you can receive vSwitch event notifications.
Subscribe to ECS events through EventBridge.
How do I resolve the
InvalidDependence.GrantAccesserror?
Cause: The instance is associated with another cloud service that has a reverse authorization link.
Solution: Release the reverse authorization link. Delete the authorization for other products and try again.
If a private link was generated through Workbench, release it as follows:
Log on to the Workbench console. On the Private Links page, check whether a reverse authorization link exists. If so, click Release Link.
Click OK to release the link, then try changing the VPC again.
How do I resolve the
InvalidDependence.NextHopOfCustomRoutererror?
Cause: The instance is the next hop in a custom route table entry.
Solution: Delete the route entry that uses the instance as the next hop:
Log on to the Route Table console. Select the region of the instance's original VPC.
On the Route Tables page, find the route that uses the instance as the next hop. Click Delete to remove it, then try changing the VPC again.
How do I resolve the
InvalidDependence.SLBerror?
Cause: The instance is in an SLB server group, even if not actively serving traffic.
Solution: Remove the instance from the SLB backend server group, then try again. See Create and manage server groups.
How do I resolve the
EnterpriseGroupLimited.MutliGroupTypeerror?
Cause: The selected security groups have inconsistent types. All selected groups must be basic or all must be enterprise.
Solution: Select security groups of the same type.
How do I resolve the
Invalidinstance.AttachedEnierror?
Cause: The instance has secondary ENIs attached.
Solution: Detach all secondary ENIs from the instance.
How do I resolve the
PrimaryEniHasSubIperror?
Cause: The primary ENI has secondary private IP addresses assigned.
Solution: Unassign the secondary private IP addresses from the instance.
References
To interconnect VPCs across accounts, use a VPC peering connection or Cloud Enterprise Network (CEN).
To migrate an instance to another zone in the same region, see Cross-zone migration.
To migrate an instance between accounts or regions, see Migrate ECS instances between different accounts or within the same account.