CreateNetworkInterface -

Creates an elastic network interface (ENI).

Usage notes

Take note of the following items:

This operation is a synchronous operation. After an ENI is created, it immediately enters the Available (Available) state and can be attached to an Elastic Compute Service (ECS) instance.
If the NetworkInterfaceId parameter is empty in the response, no ENI is created. Call the operation again to create an ENI.
An ENI can be attached only to a single instance that resides in a Virtual Private Cloud (VPC).
When an ENI is detached from an instance and reattached to another instance, the attributes of the ENI remain unchanged and network traffic is redirected to the new instance.
When you call this operation to create an ENI, you can assign up to 49 secondary private IP addresses to the ENI.
If you want to assign IPv6 addresses when you create an ENI, make sure that IPv6 has been enabled for the vSwitch with which to associate the ENI. For more information, see What is an IPv6 gateway?
A quota is imposed on the number of ENIs that can be created per Alibaba Cloud region per account. You can view the quota in the ECS console. For more information, see View and increase resource quotas.

For information about examples on how to call this operation, see Create an ENI.

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	CreateNetworkInterface	The operation that you want to perform. Set the value to CreateNetworkInterface.
RegionId	String	Yes	cn-hangzhou	The ID of the region in which to create the ENI. You can call the DescribeRegions operation to query the most recent region list.
Tag.N.Key	String	No	TestKey	The key of tag N to add to the ENI. Valid values of N: 1 to 20. The tag key cannot be an empty string. The tag key can be up to 128 characters in length and cannot contain `http://` or `https://`. The tag key cannot start with acs: or aliyun.
Tag.N.Value	String	No	TestValue	The value of tag N to add to the ENI. Valid values of N: 1 to 20. The tag value can be an empty string. The tag value can be up to 128 characters in length and cannot contain `http://` or `https://`. The tag value cannot start with acs:.
ResourceGroupId	String	No	rg-bp67acfmxazb4ph****	The ID of the resource group to which to assign the ENI. You can call the ListResourceGroups operation to query the most recent resource group list.
VSwitchId	String	Yes	vsw-bp1s5fnvk4gn2tws03****	The ID of the vSwitch in the specified VPC. Private IP addresses are assigned to the ENI from within the CIDR block of the vSwitch.
PrimaryIpAddress	String	No	172.17..	The primary private IP address to assign to the ENI. The specified IP address must be an idle IP address within the CIDR block of the vSwitch. If this parameter is not specified, an idle IP address is assigned from within the vSwitch CIDR block at random.
SecurityGroupId	String	No	sg-bp1fg655nh68xyz9i****	The ID of the security group. The security group and the ENI must belong to the same VPC. Note You must specify `SecurityGroupId` or `SecurityGroupIds.N` but not both.
NetworkInterfaceName	String	No	testNetworkInterfaceName	The name of the ENI. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with `http://` or `https://`. The name can contain letters, digits, colons (:), underscores (_), and hyphens (-). This parameter is empty by default.
Description	String	No	testDescription	The description of the ENI. The description must be 2 to 256 characters in length and cannot start with `http://` or `https://`. This parameter is empty by default.
Visible	Boolean	No	null	Note This parameter is no longer used.
InstanceType	String	No	null	Note This parameter is no longer used.
BusinessType	String	No	null	Note This parameter is no longer used.
SecondaryPrivateIpAddressCount	Integer	No	1	The number of private IP addresses to be automatically created by ECS. Valid values: 1 to 49.
QueueNumber	Integer	No	1	The number of queues supported by the ENI. Valid values: 1 to 2048. When you attach the ENI to an instance, make sure that the value of this parameter is less than the maximum number of queues per ENI that is allowed for the instance type. To view the maximum number of queues per ENI allowed for an instance type, you can call the DescribeInstanceTypes operation and then check the return value of `MaximumQueueNumberPerEni`. This parameter is empty by default. If you do not specify this parameter, the default number of queues per ENI for the instance type of an instance is used when you attach the ENI to the instance. To learn about the default number of queues per ENI for an instance type, you can call the DescribeInstanceTypes operation and then check the return value of `SecondaryEniQueueNumber`.
ClientToken	String	No	123e4567-e89b-12d3-a456-426655440000	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 different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.
NetworkInterfaceTrafficMode	String	No	Standard	The communication mode of the ENI. Valid values: Standard: uses the TCP communication mode. HighPerformance: uses the remote direct memory access (RDMA) communication mode with Elastic RDMA Interface (ERI) enabled. Note A value of HighPerformance supports only the c7re RDMA-enhanced instance family. The maximum number of ENIs in RDMA mode that can be attached to a c7re instance is determined based on the instance type. The c7re instance family is in invitational preview in Beijing Zone K. For more information, see Overview of instance families. Default value: Standard.
QueuePairNumber	Integer	No	22	Note This parameter is in invitational preview and is not publicly available.
SecurityGroupIds.N	String	No	sg-bp1fg655nh68xyz9i****	The ID of security group N to which to assign the ENI. The security group and the ENI must belong to the same VPC. The valid values of N are determined based on the maximum number of security groups to which an ENI can be assigned. For more information, see Limits. Note You must specify `SecurityGroupId` or `SecurityGroupIds.N` but not both.
PrivateIpAddress.N	String	No	172.17..	The secondary private IP address N to assign to the ENI. This IP address must be an idle IP address within the CIDR block of the vSwitch with which to associate the ENI. Valid values of N: 0 to 10. Note To assign secondary private IP addresses to the ENI, you must specify `PrivateIpAddress.N` or `SecondaryPrivateIpAddressCount` parameters but not both.
Ipv6Address.N	String	No	2001:db8:1234:1a00::****	The IPv6 address N to assign to the ENI. Valid values of N: 1 to 10. Example: Ipv6Address.1=2001:db8:1234:1a00::** Note** To assign IPv6 addresses to the ENI, you must specify `Ipv6Addresses.N` or `Ipv6AddressCount` but not both.
Ipv6AddressCount	Integer	No	1	The number of randomly generated IPv6 addresses to assign to the ENI. Valid values: 1 to 10. Note To assign IPv6 addresses to the ENI, you must specify `Ipv6Addresses.N` or `Ipv6AddressCount` but not both.
Ipv4Prefix.N	String	No	192.168../28	The IPv4 prefix N to assign to the ENI. Valid values of N: 1 to 10. Note To assign IPv4 prefixes to the ENI, you must specify Ipv4Prefix.N or Ipv4PrefixCount but not both.
Ipv4PrefixCount	Integer	No	1	The number of IPv4 prefixes to assign to the ENI. Valid values: 1 to 10. Note To assign IPv4 prefixes to the ENI, you must specify Ipv4Prefix.N or Ipv4PrefixCount but not both.
Ipv6Prefix.N	String	No	2001:db8:1234:1a00:****::/80	The IPv6 prefix N to assign to the ENI. Valid values of N: 1 to 10. Note To assign IPv6 prefixes to the ENI, you must specify Ipv6Prefix.N or Ipv6PrefixCount but not both.
Ipv6PrefixCount	Integer	No	1	The number of IPv6 prefixes to assign to the ENI. Valid values: 1 to 10. Note To assign IPv6 prefixes to the ENI, you must specify Ipv6Prefix.N or Ipv6PrefixCount but not both.
DeleteOnRelease	Boolean	No	true	Specifies whether to release the ENI when the associated instance is released. Valid values: true false

Response parameters

Parameter	Type	Example	Description
Status	String	Available	The status of the ENI.
Type	String	Secondary	The type of the ENI.
VpcId	String	vpc-bp1j7w3gc1cexjqd****	The ID of the VPC to which the ENI belongs.
NetworkInterfaceName	String	my-eni-name	The name of the ENI.
MacAddress	String	00:16:3e:12::	The media access control (MAC) address of the ENI.
NetworkInterfaceId	String	eni-bp14v2sdd3v8htln****	The ID of the ENI.
ServiceID	Long	12345678910	The ID of the distributor to which the ENI belongs.
OwnerId	String	123456****	The ID of the account to which the ENI belongs.
ServiceManaged	Boolean	true	Indicates whether the user of the ENI is an Alibaba Cloud service or a distributor.
VSwitchId	String	vsw-bp16usj2p27htro3****	The ID of the vSwitch.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The ID of the request.
Description	String	testDescription	The description of the ENI.
ResourceGroupId	String	rg-2ze88m67qx5z****	The ID of the resource group to which the ENI belongs.
ZoneId	String	cn-hangzhou-e	The zone ID of the ENI.
PrivateIpAddress	String	172.17..	The private IP address of the ENI.
SecurityGroupIds	Array of String	sg-bp18kz60mefsicfg****	The IDs of the security groups to which the ENI belongs.
PrivateIpSets	Array of PrivateIpSet		The private IP addresses of the ENI.
PrivateIpSet
PrivateIpAddress	String	172.17..	The private IP address of the ENI.
Primary	Boolean	true	Indicates whether the IP address is the primary private IP address.
Tags	Array of Tag		The tags of the ENI.
Tag
TagValue	String	TestValue	The tag value of the ENI.
TagKey	String	TestKey	The tag key of the ENI.
Ipv6Sets	Array of Ipv6Set		The IPv6 addresses assigned to the ENI.
Ipv6Set
Ipv6Address	String	2001:db8:1234:1a00::****	The IPv6 address assigned to the ENI.
Ipv4PrefixSets	Array of Ipv4PrefixSet		The IPv4 prefixes assigned to the ENI.
Ipv4PrefixSet
Ipv4Prefix	String	192.168../28	The IPv4 prefix assigned to the ENI.
Ipv6PrefixSets	Array of Ipv6PrefixSet		The IPv6 prefixes assigned to the ENI.
Ipv6PrefixSet
Ipv6Prefix	String	2001:db8:1234:1a00:****::/80	The IPv6 prefix assigned to the ENI.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=CreateNetworkInterface
&RegionId=cn-hangzhou
&SecurityGroupIds.1=sg-bp18kz60mefsicfg****
&VSwitchId=vsw-bp1s5fnvk4gn2tws03****
&Tag.1.Key=TestKey
&Tag.1.Value=TestValue
&ResourceGroupId=rg-bp67acfmxazb4ph****
&PrimaryIpAddress=172.17.**.**
&NetworkInterfaceName=testNetworkInterfaceName
&Description=testDescription
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&Ipv6AddressCount=1
&<Common request parameters>

Sample success responses

XML format

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

<CreateNetworkInterfaceResponse>
    <Description>testDescription</Description>
    <Status>Available</Status>
    <PrivateIpAddress>172.17.**.**</PrivateIpAddress>
    <ServiceManaged>false</ServiceManaged>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <ResourceGroupId>rg-2ze88m67qx5z****</ResourceGroupId>
    <ZoneId>cn-hangzhou-e</ZoneId>
    <VSwitchId>vsw-bp16usj2p27htro3****</VSwitchId>
    <NetworkInterfaceName>my-eni-name</NetworkInterfaceName>
    <MacAddress>00:16:3e:12:**:**</MacAddress>
    <NetworkInterfaceId>eni-bp14v2sdd3v8htln****</NetworkInterfaceId>
    <SecurityGroupIds>
        <SecurityGroupId>sg-bp18kz60mefsicfg****</SecurityGroupId>
    </SecurityGroupIds>
    <Type>Secondary</Type>
    <Ipv6Sets>
        <Ipv6Set>
            <Ipv6Address>2001:db8:1234:1a00::****</Ipv6Address>
        </Ipv6Set>
    </Ipv6Sets>
    <VpcId>vpc-bp1j7w3gc1cexjqd****</VpcId>
    <OwnerId>123456****</OwnerId>
    <Tags>
        <Tag>
            <TagKey>TestKey</TagKey>
            <TagValue>TestValue</TagValue>
        </Tag>
    </Tags>
    <PrivateIpSets>
        <PrivateIpSet>
            <PrivateIpAddress>172.17.**.**</PrivateIpAddress>
            <Primary>true</Primary>
        </PrivateIpSet>
    </PrivateIpSets>
</CreateNetworkInterfaceResponse>

JSON format

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

{
  "Description" : "testDescription",
  "Status" : "Available",
  "PrivateIpAddress" : "172.17.**.**",
  "ServiceManaged" : false,
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "ResourceGroupId" : "rg-2ze88m67qx5z****",
  "ZoneId" : "cn-hangzhou-e",
  "VSwitchId" : "vsw-bp16usj2p27htro3****",
  "NetworkInterfaceName" : "my-eni-name",
  "MacAddress" : "00:16:3e:12:**:**",
  "NetworkInterfaceId" : "eni-bp14v2sdd3v8htln****",
  "SecurityGroupIds" : {
    "SecurityGroupId" : [ "sg-bp18kz60mefsicfg****" ]
  },
  "Type" : "Secondary",
  "Ipv6Sets" : {
    "Ipv6Set" : [ {
      "Ipv6Address" : "2001:db8:1234:1a00::****"
    } ]
  },
  "VpcId" : "vpc-bp1j7w3gc1cexjqd****",
  "OwnerId" : "123456****",
  "Tags" : {
    "Tag" : [ {
      "TagKey" : "TestKey",
      "TagValue" : "TestValue"
    } ]
  },
  "PrivateIpSets" : {
    "PrivateIpSet" : [ {
      "PrivateIpAddress" : "172.17.**.**",
      "Primary" : true
    } ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	MissingParameter	%s	A required parameter is not specified.
400	UnsupportedParameter	%s	A specified parameter is not supported.
400	InvalidParameter	%s	Invalid parameter value.
400	InvalidInstanceID.Malformed	%s	Invalid InstanceId format.
400	InvalidOperation.InvalidEcsState	%s	This operation cannot be performed on the instance in the current state.
400	InvalidOperation.InvalidEniState	%s	This operation cannot be performed on the ENI in the current state.
400	InvalidOperation.DetachPrimaryEniNotAllowed	%s	The primary ENI cannot be detached from the instance.
400	Forbidden.RegionId	%s	The service is unavailable in the region for the moment.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	Invalid Tag.N.Key value.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	Invalid Tag.N.Value value.
400	InvalidOperation.EniCountExceeded	The maximum number of eni in a enterprise security group is exceeded.	The maximum number of ENIs in the advanced security group is exceeded.
400	IncorrectVSwitchStatus	The current status of vSwitch does not support this operation.	The operation cannot be performed on the vSwitch in the current state.
400	JoinedGroupLimitExceed	%s	The maximum number of security groups to which the specified resource can be assigned is exceeded. For more information, see the return value of the %s placeholder in the error message.
400	InvalidPrivateIpAddress.Duplicated	Specified private IP address is duplicated.	The specified private IP address is already in use. Try a different IP address.
400	InvalidParameter.Conflict	%s	Invalid parameter value. Check whether parameter conflicts exist. %s is a variable. An error message is dynamically returned based on call conditions.
400	IncorrectVSwitchStatus	The current status of virtual switch does not support this operation.	The specified vSwitch is in the Pending state and cannot be deleted.
403	InvalidUserType.NotSupported	%s	Your account does not support this operation.
403	Abs.InvalidAccount.NotFound	%s	Your Alibaba Cloud account is not found, or your AccessKey pair has expired.
403	Forbidden.NotSupportRAM	%s	Resource Access Management (RAM) users do not have the permissions to perform this operation.
403	Forbidden.SubUser	%s	You have no access to the resource. Contact the owner of the Alibaba Cloud account.
403	MaxEniCountExceeded	%s	The maximum number of ENIs that can be managed is exceeded.
403	EniPerInstanceLimitExceeded	%s	The maximum number of ENIs that can be attached to the instance is exceeded.
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	The maximum number of instances in the specified security group is exceeded.
403	InvalidSecurityGroupId.NotVpc	%s	Invalid security group ID. The network type of the specified security group is not VPC.
403	InvalidOperation.InvalidEniType	%s	This operation cannot be performed on this type of ENI.
403	InvalidVSwitchId.IpNotEnough	%s	The number of available IP addresses on the specified vSwitch is insufficient.
403	InvalidVSwitchId.IpInvalid	%s	Invalid private IP address.
403	QuotaExceed.Tags	%s	The maximum number of tags is exceeded. %s is a variable. An error message is dynamically returned based on call conditions.
403	InvalidIp.IpRepeated	%s	The IP address already exists.
403	MaxEniPrivateIpsCountExceeded	%s	The maximum number of secondary private IP addresses that can be assigned to the specified ENI has been exceeded. For more information, see the return value of the %s placeholder in the error message.
403	InvalidOperation.ResourceManagedByCloudProduct	%s	You cannot modify security groups managed by cloud services.
403	InvalidParameter.InvalidEniQueueNumber	%s	Invalid QueueNumber value. For more information, see the return value of the %s placeholder in the error message.
403	InvalidOperation.MaxEniQueueNumberExceeded	%s	The maximum number of queues per ENI is exceeded. For more information, see the return value of the %s placeholder in the error message.
403	InvalidOperation.ExceedInstanceTypeQueueNumber	%s	The maximum number of queues for all ENIs on an instance is exceeded. For more information, see the return value of the %s placeholder in the error message.
403	InvalidIp.IpPrefixMaskNotSame	The ip prefixes %s are illegal which mask must be same.	The IP prefix masks are not the same.
403	InvalidIp.IpPrefixMaskInvalid	The ip prefixes mask %s is illegal which must be between %s and %s.	The IP prefix mask is invalid and is not within the valid range.
403	InvalidIp.IpPrefixMaskIllegal	The ip prefix mask is illegal.	The IP prefix mask is invalid.
403	InvalidIp.IpPrefixIllegal	The ip prefixes %s is/are illegal.	The IP prefix is invalid and is not in the CIDR format.
403	InvalidIp.IpPrefixMustInReserveSegment	The ip prefix must in vswitch reserve segment.	The IP prefix is invalid and is not in the reserved CIDR block of the vSwitch.
403	InvalidIp.IpPrefixNotAvailable	The ip prefix is/are not available.	The IP prefix is unavailable.
403	InvalidIp.IpPrefixNotStrict	The ip prefix must be strict cidr format.	The IP prefix is invalid and is not in the CIDR format.
403	InvalidVSwitchId.IpPrefixNotEnough	The specified vSwitch has not enough ip prefix.	The number of IP prefixes in the specified vSwitch is insufficient.
404	InvalidEcsId.NotFound	%s	The instance ID is not found.
404	InvalidEniId.NotFound	%s	The ENI ID is not found.
404	InvalidVSwitchId.NotFound	%s	The vSwitch ID is not found.
404	InvalidSecurityGroupId.NotFound	%s	The specified security group ID does not exist.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The resource group does not exist.
404	InvalidOperation.VSwitchIpv6Disabled	The specified VSwitch does not support Ipv6 feature.	The specified vSwitch does not support IPv6.
404	InvalidOperation.AddressAlreadyAllocated	The specified ip address has been already allocated.	The IP address is already in use.
404	InvalidOperation.SlaveEniMustHaveBondingEni	Create slave eni must have bonding eni first.	You must create bond ENIs before you can create secondary ENIs.
404	InvalidOperation.VSwitchCidrReservationNotExist	The specified vSwitch has no cidr reservation.	No reserved CIRD block is available for the specified vSwitch.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	An internal error occurred. Try again later.
500	InvalidOperation.RegionNotSupportIpPrefix	The current region does not support ip prefix.	IP prefixes cannot be assigned in the region.

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