Creates an elastic network interface (ENI).
Description
- An ENI is in the Available state after it is created.
- An ENI can be bound only to a single instance of the Virtual Private Cloud (VPC) type within the same zone.
- An ENI can be bound only to a single instance. Before you can bind an ENI to another instance, you must unbind the ENI from the current instance.
- When an ENI is bound to another instance, the attributes of the ENI remain unchanged and the data traffic is redirected to the bound instance.
- 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?
- By default, up to 100 ENIs can be created per region per Alibaba Cloud account. To increase this quota, submit a ticket.
Debugging
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 current list of regions. |
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 value cannot
be an empty string. It can be up to 128 characters in length and cannot start with
acs: or aliyun. It cannot contain |
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. It can be up to 128 characters in length and cannot start with
acs: or contain |
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 with which to associate the ENI. 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 with which to associate the ENI. 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 to which to assign the ENI. 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 description must be 2 to 128 characters in length. It must
start with a letter and cannot start with 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 This parameter is empty by default. |
Visible | Boolean | No | null |
Note This parameter is deprecated.
|
InstanceType | String | No | null |
Note This parameter is deprecated.
|
BusinessType | String | No | null |
Note This parameter is deprecated.
|
SecondaryPrivateIpAddressCount | Integer | No | 1 |
The number of private IP addresses to be automatically created by ECS. |
QueueNumber | Integer | No | 1 |
The number of queues supported by the ENI. Valid values: 1 to 2048. When you bind an ENI to an instance, make sure that the value of this parameter for
the ENI is smaller than the maximum number of queues per ENI 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 to query the By default, this parameter is empty. If you do not specify this parameter for the
ENI, the default number of queues per ENI for the instance type of an instance is
used when you bind the ENI to the instance. To view the default number of queues per
ENI for an instance type, you can call the DescribeInstanceTypes operation to query the |
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 a client token. Make sure that a unique client token is used for each request. The ClientToken value 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 model of the ENI. Valid values:
Note A value of HighPerformance supports only the c7re RDMA-enhanced instance family. The
maximum number of ENIs in RDMA mode that can be bound 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 Instance families.
Default value: Standard. |
QueuePairNumber | Integer | No | 22 |
Note This parameter is in invitational preview and unavailable for general users.
|
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.**.** |
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::**** |
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 IPv6 addresses to generate at random for 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.
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
Status | String | Available |
The state 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 is an Alibaba Cloud service or a distributor. |
VSwitchId | String | vsw-bp16usj2p27htro3**** |
The ID of the vSwitch with which the ENI is associated. |
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 |
Private IP addresses of the ENI. |
|
PrivateIpSet | |||
PrivateIpAddress | String | 172.17.**.** |
The private IP address of the instance to which the ENI is bound. |
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 of the ENI. |
|
Ipv6Set | |||
Ipv6Address | String | 2001:db8:1234:1a00::**** |
The IPv6 address. |
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
HttpCode | Error code | Error message | Description |
---|---|---|---|
400 | MissingParameter | %s | The error message returned because a required parameter is not specified. |
400 | UnsupportedParameter | %s | The error message returned because a specified parameter is not supported. |
400 | InvalidParameter | %s | The error message returned because a specified parameter is invalid. |
400 | InvalidInstanceID.Malformed | %s | The error message returned because the specified InstanceId parameter is invalid. |
400 | InvalidOperation.InvalidEcsState | %s | The error message returned because the operation is not supported while the instance is in the current state. |
400 | InvalidOperation.InvalidEniState | %s | The error message returned because the operation is not supported while the ENI is in the current state. |
400 | InvalidOperation.DetachPrimaryEniNotAllowed | %s | The error message returned because the ENI could not be unbound from an instance. |
400 | Forbidden.RegionId | %s | The error message returned because the service is unavailable in the current region for the moment. |
400 | Duplicate.TagKey | The Tag.N.Key contain duplicate key. | The error message returned because the specified tag key already exists. Tag keys must be unique. |
400 | InvalidTagKey.Malformed | The specified Tag.n.Key is not valid. | The error message returned because the specified tag key-related parameter is invalid. |
400 | InvalidTagValue.Malformed | The specified Tag.n.Value is not valid. | The error message returned because the specified tag value-related parameter is invalid. |
400 | JoinedGroupLimitExceed | %s | The error message returned because the maximum number of security groups to which the specified resource can be assigned has been 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 error message returned because the specified private IP address is already in use. Try a different IP address. |
400 | InvalidParameter.Conflict | %s | The error message returned because a specified parameter is invalid. Check whether parameter conflicts exist. %s is a variable. An error message is dynamically returned based on call conditions. |
403 | InvalidUserType.NotSupported | %s | The error message returned because your account does not support this operation. |
403 | Abs.InvalidAccount.NotFound | %s | The error message returned because your Alibaba Cloud account does not exist or because your AccessKey pair has expired. |
403 | Forbidden.NotSupportRAM | %s | The error message returned because RAM users are not authorized to perform this operation. |
403 | Forbidden.SubUser | %s | The error message returned because you are not authorized to manage this resource. Contact the owner of the Alibaba Cloud account for authorization. |
403 | MaxEniCountExceeded | %s | The error message returned because the maximum number of ENIs that can be managed has been reached. |
403 | EniPerInstanceLimitExceeded | %s | The error message returned because the maximum number of ENIs that can be bound to the specified instance has been reached. |
403 | InvalidOperation.AvailabilityZoneMismatch | %s | The error message returned because the operation is invalid. |
403 | InvalidOperation.VpcMismatch | %s | The error message returned because this operation is invalid. Check whether the VPC in the operation corresponds to other parameters. |
403 | SecurityGroupInstanceLimitExceed | %s | The error message returned because the maximum number of instances in the security group has been reached. |
403 | InvalidSecurityGroupId.NotVpc | %s | The error message returned because the specified SecurityGroupId parameter is invalid and the network type of the security group is not VPC. |
403 | InvalidOperation.InvalidEniType | %s | The error message returned because the operation is not supported while the ENI is of the current type. |
403 | InvalidVSwitchId.IpNotEnough | %s | The error message returned because available IP addresses within the CIDR block of the specified vSwitch are insufficient. |
403 | InvalidVSwitchId.IpInvalid | %s | The error message returned because the specified private IP address is invalid. |
403 | QuotaExceed.Tags | %s | The error message returned because the number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions. |
403 | InvalidIp.Address | %s | The error message returned because the specified IPv6 address is invalid. |
403 | InvalidIp.IpRepeated | %s | The error message returned because the specified IP address already exists. |
403 | MaxEniPrivateIpsCountExceeded | %s | The error message returned because the maximum number of secondary private IP addresses that can be assigned to the ENI has been reached. For more information, see the return value of the %s placeholder in the error message. |
403 | InvalidOperation.ResourceManagedByCloudProduct | %s | The error message returned because you cannot modify security groups managed by cloud services. |
403 | InvalidParameter.InvalidEniQueueNumber | %s | The error message returned because the specified NetworkInterfaceQueueNumber parameter is invalid. For more information, see the return value of the %s placeholder in the error message. |
403 | InvalidOperation.MaxEniQueueNumberExceeded | %s | The error message returned because the maximum number of queues per ENI has been reached. For more information, see the return value of the %s placeholder in the error message. |
403 | InvalidOperation.ExceedInstanceTypeQueueNumber | %s | The error message returned because the maximum number of queues for all ENIs on an instance has been reached. For more information, see the return value of the %s placeholder in the error message. |
404 | InvalidEcsId.NotFound | %s | The error message returned because the specified instance ID does not exist. |
404 | InvalidEniId.NotFound | %s | The error message returned because the specified ENI ID does not exist. |
404 | InvalidVSwitchId.NotFound | %s | The error message returned because the specified vSwitch ID does not exist. |
404 | InvalidSecurityGroupId.NotFound | %s | The error message returned because the specified security group ID does not exist. |
404 | InvalidResourceGroup.NotFound | The ResourceGroup provided does not exist in our records. | The error message returned because the specified resource group does not exist. |
500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | The error message returned because an internal error has occurred. Try again later. |
For a list of error codes, visit the API Error Center.