All Products
Search

This Product

    Elastic Compute Service:AttachNetworkInterface

    Document Center

    Elastic Compute Service:AttachNetworkInterface

    Last Updated:Sep 13, 2024

    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

    OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

    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 Resources is 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.
    OperationAccess levelResource typeCondition keyAssociated operation
    ecs:AttachNetworkInterfaceupdate
    • NetworkInterface
      acs:ecs:{#regionId}:{#accountId}:eni/{#eniId}
    • Instance
      acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    RegionIdstringYes

    The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

    		cn-hangzhou
    NetworkInterfaceIdstringYes

    The ID of the ENI.

    		eni-bp17pdijfczax1huji****
    InstanceIdstringYes

    The instance ID.

    		i-bp16qstyvxj9gpqw****
    TrunkNetworkInstanceIdstringNo

    The ID of the trunk ENI.

    Note This parameter is unavailable.
    		eni-f8zapqwj1v1j4ia3****
    WaitForNetworkConfigurationReadybooleanNo
    Note This parameter is no longer supported.
    		null
    NetworkCardIndexintegerNo

    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

    ParameterTypeDescriptionExample
    object
    RequestIdstring

    The request ID.

    		473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

    Examples

    Sample success responses

    JSONformat

    {
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

    Error codes

    HTTP status codeError codeError messageDescription
    400MissingParameter%sA parameter is not specified.
    400UnsupportedParameter%sThe parameter is not supported.
    400InvalidParameter%sThe specified parameter is invalid.
    400InvalidInstanceID.Malformed%sThe specified InstanceId parameter is invalid.
    400InvalidOperation.InvalidRegion%sThe specified RegionId parameter is invalid.
    400InvalidOperation.InvalidEcsState%s-
    400InvalidOperation.InvalidEniState%s-
    400InvalidOperation.DetachPrimaryEniNotAllowed%s-
    400Forbidden.RegionId%sThe service is unavailable in the current region.
    400InvalidOperation.InvalidGeneration%s-
    400InvalidParams.EniId%sThe specified EniId parameter is invalid.
    400InvalidOperation.UserNotSupportNetworkCardUser not support network card.-
    400InvalidOperation.ConnectionTrackingConfigNotSupportMemberEniMember eni not support ConnectionTrackingConfiguration.Network connection configurations cannot be specified for member network interfaces.
    400InvalidOperation.InvalidEcsState%s.The current state of the instance does not support this operation.
    400InvalidParameter.NetworkCardIndexInvalidThe 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
    403InvalidUserType.NotSupported%sYour account does not support this operation.
    403Abs.InvalidAccount.NotFound%sYour Alibaba Cloud account does not exist or your AccessKey pair has expired.
    403Forbidden.NotSupportRAM%sRAM users are not authorized to perform this operation.
    403Forbidden.SubUser%sYou are not authorized to manage this resource. Contact the owner of the Alibaba Cloud account for authorization.
    403MaxEniCountExceeded%sThe maximum number of ENIs that can be managed has been reached.
    403EniPerInstanceLimitExceeded%sThe maximum number of ENIs that can be attached to the specified instance has been reached.
    403InvalidOperation.AvailabilityZoneMismatch%sThe operation is invalid.
    403InvalidOperation.VpcMismatch%sThe operation is invalid. Check whether the VPC in the operation corresponds to other parameters.
    403SecurityGroupInstanceLimitExceed%s-
    403InvalidSecurityGroupId.NotVpc%sThe specified SecurityGroupId parameter is invalid and the network type of the security group is not VPC.
    403InvalidOperation.InvalidEniType%s-
    403InvalidInstanceId.NotFound%sThe specified instance does not exist. Check whether the InstanceId parameter is valid.
    403InvalidEni.NotSameVpc%sThe 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.
    403InvalidOperation.Ipv4CountExceeded%sThe operation is valid because the maximum number of IPv4 addresses has been reached.
    403InvalidOperation.EniServiceManaged%sThe operation is invalid.
    403InvalidOperation.MultiGroupTypeThe specified instance can't join different types of security group.-
    403InvalidOperation.NotSupportEnterpriseGroupThe specified instance type doesn't support enterprise level security group.-
    403InvalidOperation.EniCountExceededThe maximum number of eni in a enterprise level security group is exceeded.-
    403InvalidOperation.EipBindModel%s-
    403InvalidOperation.Ipv6NotSupport%s-
    403InvalidOperation.HotPlugNotSupport%sThe 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.
    403InvalidInstance.NetworkType%s-
    403InvalidOperation.InvalidTrunkEniStatus%s-
    403InvalidOperation.TrunkingIsNotAllowed%s-
    403InvalidOperation.InstanceTypeNotSupportEniTrunking%s-
    403InvalidOperation.EniTypeNotSupportTrunking%sThe 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.
    403InvalidOperation.EniTrunkDeviceFull%s-
    403InvalidParameter.EniNotBelongTrunk%sThe specified ENI is not in trunk mode. For more information, see the return value of the %s placeholder in the error message.
    403InvalidOperation.EniTypeNotSupportAttachToTrunk%s-
    403InvalidParameter.EniNotBelongEcs%s-
    403InvalidParameter.InvalidEniQueueNumber%s-
    403InvalidOperation.MaxEniQueueNumberExceeded%s-
    403InvalidOperation.ExceedInstanceTypeQueueNumber%sThe 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.
    403InvalidOperation.HighPerformanceTrafficModeNotSupportTrunkEni%s-
    403InvalidOperation.HighPerformanceTrafficModeNotSupportMemberEni%s-
    403InvalidOperation.InstanceTypeNotSupportHighPerformanceTrafficMode%s-
    403InvalidOperation.EniTrafficModeNotSupportIpv6%s-
    403InvalidOperation.MaxEniQueuePairNumberExceed%s-
    403InvalidParameter.InvalidQueuePairNumber%s-
    403InvalidOperation.EniQueuePairNumberOverflow%s-
    403InvalidOperation.HighPerformanceEniPerInstanceLimitExceeded%s-
    403InvalidEni.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.
    403InvalidOperation.Ipv6CountExceeded%s.The operation is invalid because the number of IPv6 has reached the upper limit.
    404InvalidEcsId.NotFound%sThe specified instance ID does not exist.
    404InvalidEniId.NotFound%sThe specified ENI ID does not exist.
    404InvalidVSwitchId.NotFound%sThe specified vSwitch does not exist.
    404InvalidSecurityGroupId.NotFound%sThe specified security group ID does not exist.
    500InternalErrorThe 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 timeSummary of changesOperation
    2024-09-12The Error code has changedView Change Details
    2024-05-08The Error code has changedView Change Details
    2024-05-07The Error code has changedView Change Details
    2023-01-04The Error code has changed. The request parameters of the API has changedView Change Details