Every elastic network interface (ENI) on an ECS instance requires a primary private IPv4 address for internal VPC communication. It is bound to the ENI and cannot be deleted, but it can be modified.
Key concepts
This diagram shows the relationship between ENIs and private IP addresses on an ECS instance. If the primary private IP address is insufficient, you can assign multiple secondary private IP addresses to the primary ENI or attach multiple secondary ENIs to the ECS instance.
-
Elastic network interface (ENI): A virtual network interface that you can attach to an ECS instance. Each instance has a primary ENI that cannot be detached. You can also attach multiple secondary ENIs to an instance as needed.
-
Primary private IPv4 address: Every ENI, whether primary or secondary, must have one primary private IPv4 address.
-
For a primary ENI, you can modify its primary private IPv4 address.
-
For a secondary ENI, you cannot modify its primary private IPv4 address after creation. To change the address, you must detach and delete the ENI, and then create and attach a new secondary ENI.
-
-
Secondary private IPv4 address: You can assign one or more secondary private IPv4 addresses to an ENI (typically the primary ENI) to enable multi-IP deployments. Before you modify the primary private IP address, you must unassign all secondary private IP addresses.
-
System reserved addresses: Within a vSwitch CIDR block, the system reserves the first IP address and the last three IP addresses, so they cannot be assigned. For example, if a vSwitch has a CIDR block of 192.168.1.0/24, the addresses 192.168.1.0, 192.168.1.253, 192.168.1.254, and 192.168.1.255 are reserved.
Specify primary private IPv4 at instance creation
When you create a new instance, you can directly 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 an existing VPC and vSwitch, or click Create VPC and Create vSwitch to go to the VPC console and create new ones. After creating them, return to the ECS instance creation wizard and click the
icon to refresh the lists 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 CIDR block.
The system validates the IP address availability in real time. The IP address you enter cannot be in use or reserved by the system.
API
When you create an ECS instance, you can call the RunInstances API operation and specify the PrivateIpAddress parameter to assign the primary private IP address.
Modify an instance's primary private IPv4 address
Modifying the primary private IP address of an existing instance is a high-risk operation that requires an instance restart and interrupts network services. Perform this operation during off-peak hours and strictly follow the steps below.
Potential impacts and risks
-
Service interruption: This operation requires the instance to be in the Stopped state, which interrupts your services.
-
Loss of instance network connectivity:
-
If the instance's operating system is configured with a static IP address, changing the private IP address causes a mismatch between the network information in the OS (such as IP address and gateway) and the actual assigned settings. This prevents you from connecting to the instance remotely or disrupts network communication.
-
Applications, cloud services (such as database connection strings, firewall whitelists, and other service configurations), and system configuration files (such as /etc/hosts) with the original primary private IP address hardcoded will fail. You must manually update them after the change.
-
Before you begin
-
Stop the instance
The instance must be in the Stopped state, and its console status cannot be Locked, Pending Release, Expired, Pending Expiration, or Pending Reclamation for Overdue Payment. If the instance is running, you must first stop the instance.
-
Complete prerequisite checks
-
Multiple private IP addresses: If the primary ENI is assigned any secondary private IPv4 or IPv6 addresses, you must first unassign the secondary private IP addresses or remove the assigned IPv6 addresses.
-
(Optional) IP address acquisition method within the instance: If the instance's OS is configured to use a static IP address, change the network configuration to use DHCP. After configuring DHCP, the instance automatically obtains its IP address, subnet mask, default gateway, and other network 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
If you only need to change to an available IP address within the same vSwitch, you can skip this step. For the following scenarios, you must prepare network resources before you change the private IP address:
-
To change the primary private IP address to a different CIDR block in the same zone, you must create a vSwitch for the destination CIDR block.
-
If the destination CIDR block is outside the current VPC's range, you must add a secondary CIDR block to the VPC and then create a vSwitch for the destination CIDR block.
-
Step 1: Change the primary private IPv4 address
Console
-
Go to the ECS console - Instances page. In the top navigation bar, select the resource group and region of the target instance.
-
Find the target instance and click the instance ID to open the details page.
-
In the All Operations section, choose .
-
Change the primary private IP address:
-
(Optional) If you need to change the vSwitch, select a destination vSwitch in the same zone.
-
Configure the Private IP Address. The new private IP address must be within the CIDR block of the destination vSwitch.
If you leave this parameter unspecified, the system automatically assigns a new primary private IP address.
-
-
After the change is complete, you can view the new vSwitch in the Configuration Information section of the Instance Details page.
After you change the primary private IP address of the primary ENI, the instance does not start automatically. You must start the instance manually.
API
Call the ModifyInstanceVpcAttribute operation to modify the vSwitch and primary private IP address of the instance's primary ENI.
After the modification is complete, you can call the DescribeInstances operation to query the instance's new vSwitch and primary private IP address.
After the vSwitch is changed, the instance does not start automatically. You must call the StartInstance operation to start it manually.
Configure primary private IPv4 for a secondary ENI
Whether you can manually specify the primary private IP address for a secondary ENI depends on its creation method:
-
Created together with an ECS instance: You cannot specify the IP address. The system automatically assigns one.
-
Created separately: You can specify an available IP address within the vSwitch's CIDR block. If you do not specify an IP address, the system automatically assigns one.
The primary private IPv4 address of a secondary ENI cannot be modified after creation. To change the address, detach the ENI. Then, create a new secondary ENI, specifying an available IP address from the vSwitch's CIDR block as the new primary private IPv4 address. Finally, attach the new ENI to the instance.