You can call this operation to assign a fixed public IP address to an ECS instance.

Description

When you call this operation, take note of the following points:

  • Before you assign a public IP address to an instance, the instance must be in the Running (Running) or Stopped (Stopped) state.
  • If the OperationLocks parameter of the instance is set to "LockReason" : "security", the instance is locked for security reasons and you cannot allocate a public IP address to it. For more information, see API behavior when an instance is locked for security reasons.
  • You can assign only one public IP address to an instance. If the instance has an existing public IP address, the AllocatedAlready error message returns.
  • After you restart the instance (RebootInstance) or start the instance (StartInstance), the new public IP address takes effect.

In addition to assigning a public IP address, you can also associate an Elastic IP Address (EIP) with the instance. For more information, see AssociateEipAddress.

Note No public IP addresses can be assigned to a VPC-type instance associated with an EIP.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String No AllocatePublicIpAddress

The operation that you want to perform. If you use a custom HTTP URL or HTTPS URL to make an API request, you must specify this parameter. Set the value to AllocatePublicIpAddress.

InstanceId String Yes i-bp1ecr********5go2go

The ID of the instance to which you want to assign a public IP address.
IpAddress String No 112.124.**.132

The public IP address of the instance.

Default value: a randomly assigned IP address.
VlanId String No 100

The VLAN ID.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.
IpAddress String 112.124.**.132

The public IP address of the instance.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=AllocatePublicIpAddress
&InstanceId=i-bp1ecr********5go2go
&IpAddress=112.124. **.132
&<Common request parameters>

Sample success responses

XML format 

<AllocatePublicIpAddressResponse>
      <RequestId>F2EF6A3B-E345-46B9-931E-0EA094818567</RequestId>
      <IpAddress>112.124. **.132</IpAddress>
</AllocatePublicIpAddressResponse>

JSON format 

{
    "RequestId": "F2EF6A3B-E345-46B9-931E-0EA094818567",
    "IpAddress": "112.124. **.132"
}

Error codes

HTTP status code Error code Error message Description
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified InstanceId parameter does not exist. Check whether the instance ID is correct.
400 InvalidIpAddress.Malformed The specified parameter "IpAddress" is not valid. The error message returned because the specified IpAddress parameter is invalid.
404 InvalidVlanId. NotFound The VlanId provided does not exist in our records. The error message returned because the specified VlanId parameter does not exist.
403 IncorrectInstanceStatus The current status of the resource does not support this operation. The error message returned because the operation is not supported while the resource is in the current state.
403 InstanceLockedForSecurity The specified operation is denied as your instance is locked for security reasons. The error message returned because the operation is not supported while the 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 error message returned because the subscription of the instance has expired. You must renew the instance before proceeding.
404 InvalidIpAddress. NotFound The specified IP is not in the specified vlan. The error message returned because the specified IP address is not in the specified VLAN.
403 IpInUse The specified IP is already in use. The error message returned because the specified IP address is in use.
403 AllocatedAlready There is an IpAddress allocated already for the specified instance. The error message returned because the instance is allocated with another IP address.
400 OperationDenied Specified operation is denied as your instance is in VPC. The error message returned because the specified operation is not applicable to VPC-type instances.
400 InsufficientPublicIp Ip address not found The error message returned because the IP address does not exist.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
400 AllocateIpInvalidInstanceBandwidth OperationDenied The InternetMaxBandwidthOut of the specified instance cannot be less than 0. The error message returned because the maximum outbound bandwidth must be greater than 0 Mbit/s.
400 OperationDenied The specified parameter "VlanId" is not valid or vlan has not enough IP address. The error message returned because the specified VlanId parameter is invalid or the maximum number of IP addresses in the VLAN has been reached.
403 NAT_PUBLIC_IP_BINDING_FAILED Binding nat public ip failed The error message returned because the public IP address failed to be bound to a gateway.
403 NAT_PUBLIC_IP_ALLOCATE_FAILED Nat public ip binding failed. The error message returned because the public IP address failed to be allocated.

For a list of error codes, visit the API Error Center.