Attaches an elastic network interface (ENI) to an Elastic Compute Service (ECS) instance that resides in a virtual private cloud (VPC). When you call this operation, you can specify parameters, such as NetworkInterfaceId, InstanceId, and NetworkCardIndex, in the request.
Operation description
Take note of the following items:
-
The ENI must be in the Available state. You can attach an ENI to only one instance that resides in the same zone and VPC as the ENI.
-
The instance must be in the Running or Stopped state. When you attach ENIs to instances of specific instance types, make sure that the instances are in the Stopped state. For more information, see the "Instance types of the ECS instances that must be in the Stopped (Stopped) state" section in the Bind an ENI topic.
Note
If the last start time of the instance (including the start time of the instance if it is a new instance, the last restart time of the instance, and the last reactivation time of the instance) is before April 1st, 2018 and the instance is in the Running state, you must call the RebootInstance operation to restart the instance. If you do not call the RebootInstance operation to restart the instance, you cannot attach the ENI to the instance.
-
You can attach multiple ENIs to one instance. For more information, see ENI overview.
-
The vSwitch to which the ENI is connected must be in the same zone and VPC as the vSwitch to which the instance is connected.
-
This operation is an asynchronous operation. After you call this operation to attach an ENI, you can view the status or events of the ENI to check whether the ENI is attached. The following figure shows the transitions between the statuses of the ENI.
- If the ENI is in the Attaching state, the ENI attachment request is sent and the ENI is being attached to the specified instance.
- If the ENI is in the InUse state, the ENI is attached to the specified instance.
- If the ENI is in the Available state, the ENI failed to be attached.
For examples on how to call this operation, see Attach an ENI.
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:AttachNetworkInterface | update | *NetworkInterface acs:ecs:{#regionId}:{#accountId}:eni/{#eniId}*Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| RegionId | string | Yes | The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
| NetworkInterfaceId | string | Yes | The ID of the ENI. | eni-bp17pdijfczax1huji**** |
| InstanceId | string | Yes | The instance ID. | i-bp16qstyvxj9gpqw**** |
| TrunkNetworkInstanceId | string | No | The ID of the trunk ENI. Note
This parameter is unavailable.
| eni-f8zapqwj1v1j4ia3**** |
| WaitForNetworkConfigurationReady | boolean | No | Note
This parameter is no longer supported.
| null |
| NetworkCardIndex | integer | No | The index of the network interface controller (NIC). Note
The value of this parameter varies based on the instance family of the specified instance. If the instance type of the specified instance does not support NICs, leave this parameter empty. If the instance type of the specified instance supports NICs, set this parameter to a valid value. For information about the valid values of this parameter, see Instance families.
| 0 |
Response parameters
Examples
Sample success responses
JSONformat
{
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}Error codes
| HTTP status code | Error code | Error message | Description |
|---|---|---|---|
| 400 | MissingParameter | %s | A parameter is not specified. |
| 400 | UnsupportedParameter | %s | The parameter is not supported. |
| 400 | InvalidParameter | %s | The specified parameter is invalid. |
| 400 | InvalidInstanceID.Malformed | %s | The specified InstanceId parameter is invalid. |
| 400 | InvalidOperation.InvalidRegion | %s | The specified RegionId parameter is invalid. |
| 400 | InvalidOperation.InvalidEcsState | %s | - |
| 400 | InvalidOperation.InvalidEniState | %s | - |
| 400 | InvalidOperation.DetachPrimaryEniNotAllowed | %s | - |
| 400 | Forbidden.RegionId | %s | The service is unavailable in the current region. |
| 400 | InvalidOperation.InvalidGeneration | %s | - |
| 400 | InvalidParams.EniId | %s | The specified EniId parameter is invalid. |
| 400 | InvalidOperation.UserNotSupportNetworkCard | User not support network card. | - |
| 400 | InvalidOperation.ConnectionTrackingConfigNotSupportMemberEni | Member eni not support ConnectionTrackingConfiguration. | Network connection configurations cannot be specified for member network interfaces. |
| 400 | InvalidOperation.InvalidEcsState | %s. | The current state of the instance does not support this operation. |
| 400 | InvalidParameter.NetworkCardIndexInvalid | The network card index is invalid or the current ECS/ENI type does not support the value. | Physical NIC properties do not meet the NIC or instance type restrictions |
| 403 | InvalidUserType.NotSupported | %s | Your account does not support this operation. |
| 403 | Abs.InvalidAccount.NotFound | %s | Your Alibaba Cloud account does not exist or your AccessKey pair has expired. |
| 403 | Forbidden.NotSupportRAM | %s | RAM users are not authorized to perform this operation. |
| 403 | Forbidden.SubUser | %s | You are not authorized to manage this resource. Contact the owner of the Alibaba Cloud account for authorization. |
| 403 | MaxEniCountExceeded | %s | The maximum number of ENIs that can be managed has been reached. |
| 403 | EniPerInstanceLimitExceeded | %s | The maximum number of ENIs that can be attached to the specified instance has been reached. |
| 403 | InvalidOperation.AvailabilityZoneMismatch | %s | The operation is invalid. |
| 403 | InvalidOperation.VpcMismatch | %s | The operation is invalid. Check whether the VPC in the operation corresponds to other parameters. |
| 403 | SecurityGroupInstanceLimitExceed | %s | - |
| 403 | InvalidSecurityGroupId.NotVpc | %s | The specified SecurityGroupId parameter is invalid and the network type of the security group is not VPC. |
| 403 | InvalidOperation.InvalidEniType | %s | - |
| 403 | InvalidInstanceId.NotFound | %s | The specified instance does not exist. Check whether the InstanceId parameter is valid. |
| 403 | InvalidEni.NotSameVpc | %s | The specified resource and the specified ENI do not belong to the same VPC. For more information, see the return value of the %s placeholder in the error message. |
| 403 | InvalidOperation.Ipv4CountExceeded | %s | The operation is valid because the maximum number of IPv4 addresses has been reached. |
| 403 | InvalidOperation.EniServiceManaged | %s | The operation is invalid. |
| 403 | InvalidOperation.MultiGroupType | The specified instance can't join different types of security group. | - |
| 403 | InvalidOperation.NotSupportEnterpriseGroup | The specified instance type doesn't support enterprise level security group. | - |
| 403 | InvalidOperation.EniCountExceeded | The maximum number of eni in a enterprise level security group is exceeded. | - |
| 403 | InvalidOperation.EipBindModel | %s | - |
| 403 | InvalidOperation.Ipv6NotSupport | %s | - |
| 403 | InvalidOperation.HotPlugNotSupport | %s | The operation is not supported while the specified resource is running. For more information, see the return value of the %s placeholder in the error message. |
| 403 | InvalidInstance.NetworkType | %s | - |
| 403 | InvalidOperation.InvalidTrunkEniStatus | %s | - |
| 403 | InvalidOperation.TrunkingIsNotAllowed | %s | - |
| 403 | InvalidOperation.InstanceTypeNotSupportEniTrunking | %s | - |
| 403 | InvalidOperation.EniTypeNotSupportTrunking | %s | The type of the ENI does not support operations related to the trunk mode. For more information, see the return value of the %s placeholder in the error message. |
| 403 | InvalidOperation.EniTrunkDeviceFull | %s | - |
| 403 | InvalidParameter.EniNotBelongTrunk | %s | The specified ENI is not in trunk mode. For more information, see the return value of the %s placeholder in the error message. |
| 403 | InvalidOperation.EniTypeNotSupportAttachToTrunk | %s | - |
| 403 | InvalidParameter.EniNotBelongEcs | %s | - |
| 403 | InvalidParameter.InvalidEniQueueNumber | %s | - |
| 403 | InvalidOperation.MaxEniQueueNumberExceeded | %s | - |
| 403 | InvalidOperation.ExceedInstanceTypeQueueNumber | %s | The maximum number of queues for all ENIs on an instance has been exceeded. For more information, see the return value of the %s placeholder in the error message. |
| 403 | InvalidOperation.HighPerformanceTrafficModeNotSupportTrunkEni | %s | - |
| 403 | InvalidOperation.HighPerformanceTrafficModeNotSupportMemberEni | %s | - |
| 403 | InvalidOperation.InstanceTypeNotSupportHighPerformanceTrafficMode | %s | - |
| 403 | InvalidOperation.EniTrafficModeNotSupportIpv6 | %s | - |
| 403 | InvalidOperation.MaxEniQueuePairNumberExceed | %s | - |
| 403 | InvalidParameter.InvalidQueuePairNumber | %s | - |
| 403 | InvalidOperation.EniQueuePairNumberOverflow | %s | - |
| 403 | InvalidOperation.HighPerformanceEniPerInstanceLimitExceeded | %s | - |
| 403 | InvalidEni.NotSameVpc | %s. | The specified resource and the specified ENI do not belong to the same VPC. See the actual return for error message% s placeholder. |
| 403 | InvalidOperation.Ipv6CountExceeded | %s. | The operation is invalid because the number of IPv6 has reached the upper limit. |
| 404 | InvalidEcsId.NotFound | %s | The specified instance ID does not exist. |
| 404 | InvalidEniId.NotFound | %s | The specified ENI ID does not exist. |
| 404 | InvalidVSwitchId.NotFound | %s | The specified vSwitch does not exist. |
| 404 | InvalidSecurityGroupId.NotFound | %s | The specified security group ID does not exist. |
| 500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | 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-09-12 | The Error code has changed | View Change Details |
| 2024-05-08 | The Error code has changed | View Change Details |
| 2024-05-07 | The Error code has changed | View Change Details |
| 2023-01-04 | The Error code has changed. The request parameters of the API has changed | View Change Details |