Each ENI has a permanent primary private IPv4 address that cannot be deleted but can be modified.
Key concepts
The following diagram shows how ENIs and private IP addresses relate on an ECS instance. To use more IP addresses, assign secondary private IPs to the primary ENI or attach secondary ENIs.
Elastic Network Interface (ENI): A virtual network interface attached to an ECS instance. Each instance has one primary ENI that cannot be detached. You can attach multiple secondary ENIs.
Primary private IPv4 address: Every ENI has exactly one primary private IPv4 address.
Primary ENI: You can modify the primary private IPv4 address.
Secondary ENI: The primary private IPv4 address cannot be modified after creation. To change it, detach and delete the ENI, then create and attach a new one.
Secondary private IPv4 address: Assign one or more secondary private IPv4 addresses to an ENI (typically the primary ENI) for multi-IP deployments. Before modifying the primary private IP address, unassign all secondary private IP addresses first.
System reserved IP address: The first and last three IPv4 addresses in a vSwitch CIDR block are reserved and cannot be assigned. For example, in 192.168.1.0/24, the reserved addresses are 192.168.1.0, 192.168.1.253, 192.168.1.254, and 192.168.1.255.
Specify a primary private IPv4 address for a new instance
When creating an instance, you can assign a static private IPv4 address to its primary ENI.
Console
Go to the ECS console - Custom Launch page.
In the Network and Zone section, select a VPC and vSwitch, or click Create VPC and Create vSwitch to create new ones. After creation, click the
icon to refresh and select the new VPC and vSwitch.Select Specify Primary Private IP Address of Primary ENI and enter an available IP address within the selected vSwitch's CIDR block.
The system checks IP availability in real time. The address must not be in use or reserved.
API
Call the RunInstances operation and specify the PrivateIpAddress parameter.
Modify the primary private IPv4 address of an existing instance
Modifying the primary private IP address requires an instance restart and causes a network interruption. Perform this operation during off-peak hours.
Potential impacts
Service interruption: The instance must be Stopped, which causes a service interruption.
Instance network connectivity loss:
If the OS uses a static IP address, changing the private IP creates a mismatch between the OS network configuration (such as the IP address and gateway) and the new settings. This can prevent remote connections or block network communication.
Applications, cloud services (such as database connection strings or firewall whitelists), or configuration files (such as
/etc/hosts) that hardcode the original IP address will break. Update them after the change.
Before you begin
Stop the instance
The instance must be in the Stopped state and not locked. If the instance is Running, stop the instance first.
Complete prerequisite checks
Multiple private IP addresses: If the primary ENI has secondary private IPv4 or IPv6 addresses, unassign the secondary private IP addresses or remove the IPv6 addresses first.
(Optional) IP retrieval method within the instance: If the OS uses a static IP address, change the network configuration to DHCP before proceeding. With DHCP, the instance automatically obtains its IP address, subnet mask, default gateway, and other settings.
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.
-
(Optional) Prepare network resources
Skip this step if you are changing to an available IP within the same vSwitch. For the following scenarios, prepare network resources in advance:
To move the primary private IP address to a different CIDR block in the same zone: Create a vSwitch for the destination CIDR block.
If the destination CIDR block is outside the current VPC's range: Add a secondary CIDR block to the VPC, then create a vSwitch for the target CIDR block.
Change the primary private IP address
Console
Go to the ECS console - Instances page. In the upper-left corner, select the resource group and region of the target instance.
Find the target instance and click its ID to open the details page.
Click All Actions and select .
Change the primary private IP address:
(Optional) To change the vSwitch, select a vSwitch in the same zone.
Set the Private IP Address. The new address must be within the CIDR block of the destination vSwitch.
If you leave this field empty, the system assigns a new primary private IP address automatically.
After the change, view the new vSwitch in the Configuration Information section of the Instance Details page.
After you change the primary private IP address, the instance does not start automatically. Start the instance manually.
API
Call the ModifyInstanceVpcAttribute operation to modify the vSwitch and primary private IP address.
Call the DescribeInstances operation to verify the new vSwitch and private IP address.
After changing the vSwitch, the instance does not start automatically. Call the StartInstance operation to start it.
Configure the primary private IPv4 address of a secondary ENI
Whether you can specify the primary private IP address for a secondary ENI depends on how it was created:
Created with an ECS instance: The IP address is assigned automatically and cannot be specified.
Created separately: You can specify any available IP address from the vSwitch's CIDR block. If not specified, the system assigns one automatically.
The primary private IPv4 address of a secondary ENI cannot be modified after creation. To change it, detach the ENI, create a new secondary ENI with the desired primary private IPv4 address, and attach it to the instance. The new address must be available within the vSwitch's CIDR block.