Assigns a static public IP address (also called system-assigned public IP address or auto-assigned public IP address) to an Elastic Compute Service (ECS) instance. When you call this operation for an ECS instance, make sure that the public bandwidth of the instance is greater than 0 Mbit/s. Only users in the whitelist can call this operation. We recommend that you assign a static public IP address to an ECS instance by calling the ModifyInstanceNetworkSpec operation to modify the public bandwidth of the instance.
Operation description
Take note of the following items:
- The instance to which you want to assign a static public IP address must be in the Running (
Running) or Stopped (Stopped) state. - If
OperationLocksin the response of the DescribeInstances operation contains"LockReason" : "security"for an instance, the instance is locked for security reasons and cannot be assigned a static public IP address. - You can assign only one static public IP address to an ECS instance. If the instance already has a static public IP address, the static public IP address is returned for the
IpAddressresponse parameter. - After you assign a static public IP address to an ECS instance, you must restart the instance ( RebootInstance ) or start the instance ( StartInstance ) for the public IP address to take effect.
If an ECS instance resides in a virtual private cloud (VPC), you can assign a static public IP address to the instance or associate an elastic IP address (EIP) with the instance. For more information, see AssociateEipAddress .
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resourcesis used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| ecs:AllocatePublicIpAddress | create | *Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| InstanceId | string | Yes | The ID of the instance to which you want to assign a public IP address. | i-bp1gtjxuuvwj17zr**** |
| IpAddress | string | No | The public IP address. If you leave this parameter empty, the system randomly assigns a public IP address to the instance. | 112.124.**.** |
| VlanId | string | No | The virtual LAN (VLAN) ID of the instance. Note
This parameter will be removed in the future. To ensure future compatibility, we recommend that you use other parameters.
| 720 |
Response parameters
Examples
Sample success responses
JSONformat
{
"IpAddress": "112.124.**.**",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}Error codes
| HTTP status code | Error code | Error message | Description |
|---|---|---|---|
| 400 | InvalidOperation.AllocateFailed | The current instance failed to allocate public IP, please try again later. | - |
| 400 | InvalidIpAddress.Malformed | The specified parameter "IpAddress" is not valid. | - |
| 400 | OperationDenied | Specified operation is denied as your instance is in VPC. | The operation is not supported while the instance resides in a VPC. |
| 400 | InsufficientPublicIp | Ip address not found. | - |
| 400 | AllocateIpInvalidInstanceBandwidth | OperationDenied The InternetMaxBandwidthOut of the specified instance cannot be less than 0. | The operation is not supported while the maximum outbound public bandwidth is not greater than 0 Mbit/s. |
| 400 | OperationDenied | The specified parameter "VlanId" is not valid or vlan has not enough IP address. | - |
| 400 | OperationDenied | The specified instance already has a public IP. | - |
| 400 | OperationDenied.CloudboxNotSupport | This operation is denied, because the specified ECS instance which is in the Cloudbox dose not support PublicIp or Eip. | - |
| 400 | OperationDenied.DedicatedRegionNotSupported | This operation is denied, because the specified ECS instance which is in the dedicated region dose not support PublicIp or Eip. | error of api not supported by the exclusive cloud |
| 403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | The resource is in a state that does not support the current operation. |
| 403 | InstanceLockedForSecurity | The specified operation is denied as your instance is locked for security reasons. | - |
| 403 | InstanceExpiredOrInArrears | The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode). | The subscription instance has expired. You must renew the instance before you can proceed. |
| 403 | IpInUse | The specified IP is already in use. | - |
| 403 | AllocatedAlready | There is an IpAddress allocated already for the specified instance. | The instance to which you attempt to assign an IP address is already assigned another IP address. |
| 403 | AllocateIp.Fail | The specified instance fails to allocate ip, please try again. | - |
| 403 | NAT_PUBLIC_IP_BINDING_FAILED | Binding nat public ip failed. | - |
| 403 | NAT_PUBLIC_IP_ALLOCATE_FAILED | Nat public ip binding failed. | The public IP address cannot be associated. |
| 403 | InvalidIpAddress.NotPublic | The specified IP is not public address. | - |
| 403 | AllocatedAlready | An IpAddress has been assigned to the specified instance. | - |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | The specified instance does not exist. |
| 404 | InvalidVlanId.NotFound | The VlanId provided does not exist in our records. | The specified VLAN ID does not exist. |
| 404 | InvalidIpAddress.NotFound | The specified IP is not in the specified vlan. | The specified IP address is not in the specified VLAN. |
| 500 | InternalError | The request processing has failed due to some unknown error. | An internal error has occurred. Try again later. |
For a list of error codes, visit the Service error codes.
Change history
| Change time | Summary of changes | Operation |
|---|---|---|
| 2024-12-20 | API Description Update. The Error code has changed | View Change Details |
| 2023-10-10 | The Error code has changed | View Change Details |