A primary private IPv4 address is the fundamental IP address for every Elastic Network Interface (ENI) on an Elastic Compute Server (ECS) instance, enabling communication within a Virtual Private Cloud (VPC). While this address is permanently bound to the ENI and cannot be deleted, you can modify it.
Core concepts
The following diagram illustrates the relationship between the ENIs of an ECS instance and its private IP addresses. If a single IP address is insufficient for your business requirements, 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, and you can attach multiple secondary ENIs 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, its primary private IPv4 address cannot be modified after creation. To change it, you must detach and delete the ENI, then create a new secondary ENI and attach it.
Secondary private IPv4 address: You can assign one or more secondary private IPv4 addresses to an ENI (typically the primary ENI) to support multi-IP deployments on a single instance. Before modifying the primary private IP address, you must first unassign all secondary private IP addresses.
System reserved IP address: A vSwitch CIDR block contains system reserved IP addresses that cannot be assigned. These include the first address and the last three IPv4 addresses in the block. 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 system reserved IP addresses.
Specify a primary private IPv4 address for a new instance
When you create a new 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 an existing VPC and vSwitch, or click Create VPC and Create vSwitch to create new ones in the VPC console. Once created, return to the ECS instance creation wizard and click the
icon to view 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 the availability of the IP address in real time. The address you enter must not be in use or be a system reserved IP address.
API
To assign a primary private IP address when creating an ECS Instance, call the RunInstances operation and specify the PrivateIpAddress parameter.
Modify the primary private IPv4 address of an existing instance's primary ENI
Modifying the primary private IP address of an existing instance is a high-risk operation that involves an instance restart and network interruption. Always perform this operation during off-peak hours and follow these steps carefully.
Impact and risks
Service interruption: This operation requires the instance to be Stopped, which causes a service interruption.
Instance network connectivity loss:
If the instance's operating system (OS) is configured with a static IP address, changing the private IP address can create 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.
Any applications, cloud services (such as database connection strings or firewall whitelists), or system configuration files (such as
/etc/hosts) that hardcode the original primary private IP address will fail. Manually update them after changing the IP address.
Step 1: Before you begin
Stop the instance
The instance must be in the Stopped state and not locked in the console. If the instance is Running, you must first stop the instance.
Complete prerequisite checks
Multiple private IP addresses: If the primary ENI has secondary private IPv4 or IPv6 addresses assigned, first unassign the secondary private IP addresses or remove the assigned IPv6 addresses.
(Optional) IP retrieval method within the instance: If the instance's OS is configured with a static IP address, we recommend changing the network configuration to DHCP (Dynamic Host Configuration Protocol) before proceeding. With DHCP, the instance automatically obtains its IP address, subnet mask, default gateway, and other configuration details.
Linux
Windows
The following steps use Windows Server 2022 as an example:
Connect to the Windows ECS instance.
For more information, see Connect to Windows.
Open Network and Sharing Center.
Click Change adapter settings.
Double-click the primary ENI named Ethernet. Then, click Properties in the Ethernet Status dialog box.
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
You can skip this step if you are changing the IP to an available one within the same vSwitch. For the following scenarios, however, you must prepare network resources in advance:
To move the primary private IP address to a different CIDR block in the same availability zone: You must create a vSwitch for the destination CIDR block.
If the destination CIDR block is outside the current VPC's CIDR block range: You must add a secondary CIDR block to the VPC and then create a vSwitch for the target CIDR block.
Step 2: Change the primary private IP address of the ECS instance's primary ENI
Console
Go to the ECS console - Instances page. In the upper-left corner of the page, select the resource group and region of the target instance.
Find the target instance and click the instance ID to go to its details page.
Click All Actions and select .
Change the primary private IP address:
(Optional) To change the vSwitch, select a destination vSwitch in the same availability zone as the current one.
Configure the Private IP Address: The new private IP address must be within the CIDR block of the destination vSwitch.
If you do not specify an IP address, 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 instance's primary ENI, the instance does not start automatically. You must manually start the instance.
API
Call the ModifyInstanceVpcAttribute operation to modify the vSwitch and primary private IP address of an ECS Instance's primary ENI.
After the modification is complete, you can call the DescribeInstances operation to verify the new vSwitch and private IP address of the instance.
After changing the vSwitch, the instance does not start automatically. You must call the StartInstance operation to manually start it.
Configure the primary private IPv4 address of a secondary ENI
Whether you can manually specify the primary private IP address for a secondary ENI depends on its creation method:
Created along with an ECS Instance: You cannot specify the IP address, it is assigned automatically.
Created separately: You can manually specify any available IP address from the vSwitch's CIDR block. If you do not specify an address, the system assigns one automatically.
The primary private IPv4 address of a secondary ENI cannot be modified after creation. To change it, you must detach the ENI, create a new secondary ENI with a specified primary private IPv4 address, and then attach it to the target instance. The new IP address must be an available address within the vSwitch's CIDR block.