Each Elastic Network Interface (ENI) on an Elastic Compute Server (ECS) instance is assigned a primary private IPv4 address. This address is used for communication within the Virtual Private Cloud (VPC). It is bound to the ENI and cannot be deleted, but can be modified.
Core concepts
The diagram below illustrates the relationship between ECS Instances, ENIs, and private IP addresses. If you need multiple IP addresses on your instance, you can assign secondary private IP addresses to the primary ENI or attach 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 non-detachable primary ENI and can have secondary ENIs attached as needed.
Primary private IPv4 address: Each ENI, whether primary or secondary, must have one primary private IPv4 address.
The primary private IPv4 address of a primary ENI can be modified.
The primary private IPv4 address of a secondary ENI cannot be modified after creation. To use a different address, detach and delete the ENI, then create 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 a multi-IP deployment on a single instance. Before you modify the primary private IP address, you must first release all secondary private IP addresses.
System reserved IP address: Within a vSwitch CIDR block, the first and the last three IPv4 addresses are reserved by the system and cannot be specified. 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 the primary private IPv4 address for the primary ENI when you create an ECS instance
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 open the VPC console and create them. Then, return to the ECS creation wizard and click the
to select the new VPC and vSwitch.Select Specify Primary Private IP Address of Primary ENI and enter an available IP address from within the CIDR block of the selected vSwitch.
The system validates the IP address availability in real time. The IP address 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 requires an instance restart and causes a network interruption. Perform this operation during a maintenance window or off-peak hours and strictly follow the steps below.
Risk assessment
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 will prevent you from making a remote connection to the instance and will disrupt its communications.
Any applications, cloud services (such as database connection strings, whitelist rules, and configurations for other services), and system configuration files (such as /etc/hosts) that use a hard-coded reference to the original IP address will fail. You must update them manually after the modification.
Step 1: Preparation
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.
Perform 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 Use Workbench to connect to a Windows instance over RDP.
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
If you only need to modify to an unassigned IP address within the same vSwitch, you can skip this step. You need to prepare network resources in the following scenarios:
To move the primary private IP address to a different CIDR block in the same availability zone, create a vSwitch for the destination CIDR block.
If the target CIDR block is outside the address space of the current VPC, first add a secondary CIDR block to the VPC and then create a vSwitch for the target CIDR block.
Step 2: Modify 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 whose vSwitch you want to modification, and click the instance ID to go to its details page.
Click All Actions and select .
Modify the primary private IP address:
(Optional) To modify the vSwitch, select a target vSwitch in the same availability zone as the current one.
Configure the Private IP Address: The new private IP address must be an available address within the CIDR block of the target vSwitch.
If you do not specify an address, the system automatically assigns a new primary private IP address.
After the modification is complete, you can view the new vSwitch in the Configuration Information section of the Instance Details page.
After you modify 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 of a secondary ENI depends on how it is created:
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 within the vSwitch's CIDR block. If you do not specify an address, the system assigns one automatically.
You cannot modify the primary private IPv4 address of a secondary ENI after creation. To modify the address, you must detach and create a new secondary ENI. When creating the new ENI, specify an available address from the vSwitch's CIDR block. Finally, attach the new ENI to the instance.