Associates an elastic IP address (EIP) with an instance in the same region.

Usage notes

  • You can associate an EIP with an Elastic Compute Service (ECS) instance, a Classic Load Balancer (CLB) instance, a secondary elastic network interface (ENI), a NAT gateway, or a high-availability virtual IP address (HAVIP) in the same region. The ECS instance and CLB instance must be deployed in a virtual private cloud (VPC).
  • AssociateEipAddress is an asynchronous operation. After you send a request, the system returns a request ID and runs the task in the background. You can call the DescribeEipAddresses operation to query the status of an EIP.
    • If the EIP is in the Associating state, the EIP is being associated. In this state, you can only query the EIP and cannot perform other operations.
    • If the EIP is in the InUse state, the EIP is associated.
  • You cannot repeatedly call AssociateEipAddress to associate an EIP with an instance within the specified period of time.

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 Yes AssociateEipAddress

The operation that you want to perform. Set the value to AssociateEipAddress.

RegionId String Yes cn-hangzhou

The ID of the region to which the EIP belongs.

You can call the DescribeRegions operation to query the most recent region list.

AllocationId String Yes eip-2zeerraiwb7ujsxdc****

The ID of the EIP that you want to associate with an instance.

InstanceId String Yes i-2zebb08phyczzawe****

The ID of the instance with which you want to associate the EIP.

You can enter the ID of a NAT gateway, CLB instance, ECS instance, secondary ENI, HAVIP, or IP address.

InstanceType String No EcsInstance

The type of instance with which you want to associate the EIP. Valid values:

  • Nat: a NAT gateway
  • SlbInstance: a CLB instance
  • EcsInstance (default): an ECS instance in a VPC
  • NetworkInterface: a secondary ENI
  • HaVip: an HAVIP
  • IpAddress: an IP address
Note If you do not set this parameter, the type of the instance with which you want to associate the EIP is EcsInstance. If the type of the instance with which you want to associate the EIP is not EcsInstance, this parameter is required.
InstanceRegionId String No cn-hangzhou

The region ID of the instance with which you want to associate the EIP.

Note This parameter is required only when the EIP is associated with a shared-bandwidth Global Accelerator (GA) instance.
PrivateIpAddress String No 192.168.XX.XX

An IP address in the CIDR block of the vSwitch.

If you do not set this parameter, the system allocates a private IP address based on the VPC ID and vSwitch ID.

Mode String No NAT

The association mode. Valid values:

  • NAT (default): NAT mode
  • MULTI_BINDED: multi-EIP-to-ENI mode
  • BINDED: cut-through mode
Note This parameter is required only when InstanceType is set to NetworkInterface.
VpcId String No vpc-257gqcdfvx6n****

The ID of the VPC that has IPv4 gateways enabled and that is deployed in the same region as the EIP.

When you associate an EIP with an IP address, the system can enable the IP address to access the Internet based on VPC route configurations.

Note This parameter is required if InstanceType is set to IpAddress. In this case, the EIP is associated with an IP address.
ClientToken String No 0c593ea1-3bea-11e9-b96b-88e9fe63****

The client token that is used to ensure the idempotence of the request.

You can use the client to generate the token, but you must make sure that the token is unique among all requests. The token can contain only ASCII characters.

Note If you do not set this parameter, the system sets ClientToken to the value of RequestId. The value of RequestId for each API request may be different.

Response parameters

Parameter Type Example Description
RequestId String 0ED8D006-F706-4D23-88ED-E11ED28DCAC0

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/?Action=AssociateEipAddress
&RegionId=cn-hangzhou
&AllocationId=eip-2zeerraiwb7ujsxdc****
&InstanceId=i-2zebb08phyczzawe****
&InstanceType=EcsInstance
&InstanceRegionId=cn-hangzhou
&PrivateIpAddress=192.168.XX.XX
&Mode=NAT
&VpcId=vpc-257gqcdfvx6n****
&ClientToken=0c593ea1-3bea-11e9-b96b-88e9fe63****
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<AssociateEipAddressResponse>
    <RequestId>0ED8D006-F706-4D23-88ED-E11ED28DCAC0</RequestId>
</AssociateEipAddressResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "0ED8D006-F706-4D23-88ED-E11ED28DCAC0"
}

Error codes

HttpCode Error code Error message Description
400 InvalidAssociation.Duplicated Specified instance already is associated. The error message returned because an EIP or a GA instance is already associated with the specified instance. You must disassociate the EIP or GA instance from the specified instance before you can perform the operation.
400 OperationDenied Specified instance is not in VPC. The error message returned because the specified instance does not exist in the VPC.
400 InvalidParameter.Mismatch Specified elastic IP address and ECS instance are not in the same region. The error message returned because the specified EIP and ECS instance do not belong to the same region.
400 IncorrectEipStatus Current elastic IP status does not support this operation The error message returned because the status of the EIP does not support the operation.
400 IncorrectInstanceStatus Current instance status does not support this operation. The error message returned because this operation cannot be performed while the instance is in the current state.
400 InvalidInstanceType.ValueNotSupported The specified value of InstanceType is not supported. The error message returned because InstanceType is set to an invalid value.
400 InvalidParameter The specified parameter is not valid. The error message returned because the parameter is set to an invalid value.
400 OperationDenied Eip of default vpc not allow this operation The error message returned because the operation is not supported by EIPs in the default VPC.
400 TaskConflict The eip operate too frequent, TaskConflict. The error message returned because the operations are too frequent and tasks conflict with each other.
400 InvalidBindingStatus The eip binding status invalid. The error message returned because the EIP is in an invalid state.
400 BIND_INSTANCE_HAVE_PORTMAP_OR_BIND_EIP The instance may have portMap or already bind eip. The error message returned because a port forwarding rule is configured for the ECS instance. Delete the port forwarding rule and try again.
400 BIND_INSTANCE_OWENER_ERROR Cannot operate the eip. The error message returned because you are unauthorized to manage the specified EIP.
400 QuotaExceeded.NumberOfEip Binded eip Quota exceed on this NatGw. The error message returned because the number of EIPs associated with the NAT gateway exceeds the upper limit.
400 InvalidAction.Denied Action is denied due to unfinished Eip configuration modification. The error message returned because the EIP configurations are not complete and the operation is denied.
400 InvalidParams.NotFound instance not found The error message returned because the specified instance does not exist.
400 Eni.Attached The eni should be detached from ecs when associating with direct eip. The error message returned because the ENI is associated with an EIP in cut-through mode. You must disassociate the ENI from the ECS instance.
400 InvalidNexthop.DirectEni The direct Eni cannot be nexthop. The error message returned because an ENI in cut-through mode cannot be specified as a next hop.
400 InvalidEIPStatus.BizDisabled The EIP has been locked. The error message returned because the EIP is locked.
400 InvalidStatus.NotAllow Bind instance status invalid The error message returned because the status of the associated instance is invalid.
400 OperationDenied.CloudBoxResourceExist The operation is not allowed because there are resources related to the cloud box in VPC. The error message returned because the VPC contains CloudBox-related resources and the operation is not allowed.
400 OperationDenied.CloudBoxVSwitchExist The operation is not allowed because a cloud box type vSwitch exists in VPC. The error message returned because the VPC contains a vSwitch of the CloudBox type and the operation is not allowed.
400 OperationDenied.NoAvailablePrivateIp The operation is failed because of VSwitch has not availalbe private ip The error message returned because the vSwitch does not have sufficient private IP addresses.
400 OperationFailed.Ipv4GatewayNotOpenedInVpc The operation is failed because Ipv4Gateway is not opened in Vpc. The error message returned because the VPC does not have IPv4 gateways enabled and the IP address failed to be associated with the EIP.
400 Forbidden The eip instance owner error The error message returned because the EIPs do not belong to you. Check whether you are unauthorized to perform the operation on the EIPs.
400 Forbidden.FinancialLocked The ip business status is invalid. The error message returned because the instance has overdue payments.
400 UnsupportedFeature.EipBindIpAddress The feature of EipBindIpAddress is not supported. The error message returned because the EIP does not support the IpAddress parameter.
400 OperationFailed.InstanceNotExist The ECS instance does not exist, or is not a VPC VM. The error message returned because the ECS instance does not exist or is not a VPC virtual machine and the EIP failed to be associated with the ECS instance.
400 OperationDenied.Ipv4GatewayExist The operation is not allowed because of Ipv4GatewayExist. The error message returned because IPv4 gateways exist in the VPC and the EIP failed to be associated.
400 OperationFailed.EipBindModeConflict Eips can not bind Eni with NAT mode and MULTI_BINDED mode at the same time. The error message returned because you cannot associate an EIP with an ENI in NAT mode and multi-EIP-to-ENI mode at the same time.
400 OperationFailed.EcsMigrating The operation is failed because of ECS is migrating. The error message returned because the ECS instance is being migrated.
404 InvalidInstanId.NotFound Specified instance does not exist. The error message returned because the specified instance does not exist. Check whether the instance ID is valid.
404 InvalidAllocationId.NotFound Specified allocation ID is not found The error message returned because the specified EIP does not exist. Check whether the specified value is valid.
404 Forbidden.RegionNotFound Specified instance is not found during access authentication. The error message returned because the region is not supported.
404 OperationDenied.VpcIpv4GatewayEnabled The operation is not allowed because of the VPC of the NAT gateway has opened IPv4 Gateway. The error message returned because IPv4 gateways are enabled for the VPC where the NAT gateway resides and the operation is denied.
503 ServiceUnavailable The request has failed due to a temporary failure of the server. The error message returned because the request failed due to a temporary server error.

For a list of error codes, see Service error codes.