All Products
Search
Document Center

Resource Orchestration Service:ALIYUN::ECS::NetworkInterface

Last Updated:Aug 15, 2023

ALIYUN::ECS::NetworkInterface is used to create an elastic network interface (ENI).

Syntax

{
  "Type": "ALIYUN::ECS::NetworkInterface",
  "Properties": {
    "Description": String,
    "SecurityGroupId": String,
    "PrimaryIpAddress": String,
    "ResourceGroupId": String,
    "VSwitchId": String,
    "NetworkInterfaceName": String,
    "Tags": List,
    "SecurityGroupIds": List,
    "PrivateIpAddresses": List,
    "SecondaryPrivateIpAddressCount": Integer,
    "Ipv6Addresses": List,
    "QueueNumber": Integer,
    "NetworkInterfaceTrafficMode": String,
    "Ipv6AddressCount": Integer
  }
}

Properties

Property

Type

Required

Editable

Description

Constraint

ResourceGroupId

String

No

Yes

The ID of the resource group.

You can call the ListResourceGroups operation to query the resource group ID.

SecurityGroupId

String

No

Yes

The ID of the security group.

The security group and the ENI must belong to the same VPC.

Note

You cannot specify both SecurityGroupId and SecurityGroupIds.

VSwitchId

String

Yes

No

The vSwitch ID.

None.

Description

String

No

Yes

The description of the ENI.

The description must be 2 to 256 characters in length. It cannot start with http:// or https://.

NetworkInterfaceName

String

No

Yes

The name of the ENI.

The name must be 2 to 128 characters in length, and can contain letters, digits, colons(:), underscores (_), and hyphens (-). It must start with a letter and cannot start with http:// or https://.

PrimaryIpAddress

String

No

No

The primary private IP address of the ENI.

The IP address that you specify must be an idle IP address within the CIDR block of the vSwitch that hosts the ENI. If you leave this property empty, an idle IP address is assigned from the vSwitch CIDR block at random.

SecondaryPrivateIpAddressCount

Integer

No

No

The number of secondary private IP addresses.

None.

Tags

List

No

Yes

The tags of the ENI.

You can add up to 20 tags.

For more information, see Tags properties.

SecurityGroupIds

List

No

Yes

The IDs of one or more security groups.

The security groups and the ENI must belong to the same VPC.

Note

You cannot specify both SecurityGroupId and SecurityGroupIds.

PrivateIpAddresses

List

No

No

The one or more secondary private IP addresses that you want to select from the CIDR block of the vSwitch that hosts the ENI.

Valid values of the number of secondary private IP addresses that can be assigned to the ENI:

  • If the ENI is in the Available state, the valid values are 1 to 10.

  • If the ENI is in the InUse state, the valid values vary based on the instance type. For more information, see Overview of instance families.

Ipv6Addresses

List

No

No

The one or more IPv6 addresses that you want to assign to the ENI.

You can specify up to 10 IPv6 addresses.

Note

If you want to assign IPv6 addresses to the ENI, you must specify the Ipv6Addresses or Ipv6AddressCount property, but not both properties.

QueueNumber

Integer

No

No

The number of queues that are supported by the ENI.

Valid values: 1 to 2048.

When you attach the ENI to an instance, make sure that the value of this property is less than the maximum number of queues per ENI allowed for the instance type. To query the maximum number of queues per ENI for the instance type, call the DescribeInstanceTypes operation and check the return value of MaximumQueueNumberPerEni.

The QueueNumber property is left empty by default. If you leave this property empty when you attach the ENI to an instance, the default number of queues per ENI allowed for the instance type is used. To query the default number of queues per ENI for the instance type, call the DescribeInstanceTypes operation and check the return value of SecondaryEniQueueNumber.

NetworkInterfaceTrafficMode

String

No

No

The communication mode of the ENI.

Valid values:

  • Standard: uses the TCP communication mode.

  • HighPerformance: enables Elastic RDMA Interface (ERI) and uses the remote direct memory access (RDMA) communication mode.

    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.

Ipv6AddressCount

Integer

No

No

The number of IPv6 addresses to generate for the ENI at random.

Valid values: 1 to 10.

Note

If you want to assign IPv6 addresses to the ENI, you must specify the Ipv6Addresses or Ipv6AddressCount property, but not both properties.

Tags syntax

"Tags": [
  {
    "Key": String,
    "Value": String
  }
]  

Tags properties

Property

Type

Required

Editable

Description

Constraint

Key

String

Yes

No

The key of the tag.

The tag key must be 1 to 128 characters in length, and cannot contain http:// or https://. It cannot start with aliyun or acs:.

Value

String

No

No

The value of the tag.

The tag value can be up to 128 characters in length, and cannot contain http:// or https://. It cannot start with aliyun or acs:.

Return values

Fn::GetAtt

  • NetworkInterfaceId: the ENI ID.

  • MacAddress: the media access control (MAC) address of the ENI.

  • PrivateIpAddress: the primary private IP address of the ENI.

  • SecondaryPrivateIpAddresses: the secondary private IP addresses of the ENI.

Examples

  • YAML format

    ROSTemplateFormatVersion: '2015-09-01'
    Parameters:
      SecurityGroupId:
        Type: String
        AssociationProperty: ALIYUN::ECS::SecurityGroup::SecurityGroupId
        Label:
           
          en: Security Group ID
      VSwitchId:
        AssociationProperty: ALIYUN::ECS::VSwitch::VSwitchId
        Type: String
        Label:
           
          en: VSwitch ID
    Resources:
      EniInstance:
        Type: ALIYUN::ECS::NetworkInterface
        Properties:
          SecurityGroupId:
            Ref: SecurityGroupId
          VSwitchId:
            Ref: VSwitchId
          NetworkInterfaceName: TestNetworkInterface
    Outputs:
      PrivateIpAddress:
        Description: The primary private ip address of your Network Interface.
        Value:
          Fn::GetAtt:
            - EniInstance
            - PrivateIpAddress
      SecondaryPrivateIpAddresses:
        Description: The secondary private IP addresses of your Network Interface.
        Value:
          Fn::GetAtt:
            - EniInstance
            - SecondaryPrivateIpAddresses
      MacAddress:
        Description: The MAC address of your Network Interface.
        Value:
          Fn::GetAtt:
            - EniInstance
            - MacAddress
      NetworkInterfaceId:
        Description: ID of your Network Interface.
        Value:
          Fn::GetAtt:
            - EniInstance
            - NetworkInterfaceId
  • JSON format

    {
      "ROSTemplateFormatVersion": "2015-09-01",
      "Parameters": {
        "SecurityGroupId": {
          "Type": "String",
          "AssociationProperty": "ALIYUN::ECS::SecurityGroup::SecurityGroupId",
          "Label": {
             
            "en": "Security Group ID"
          }
        },
        "VSwitchId": {
          "AssociationProperty": "ALIYUN::ECS::VSwitch::VSwitchId",
          "Type": "String",
          "Label": {
             
            "en": "VSwitch ID"
          }
        }
      },
      "Resources": {
        "EniInstance": {
          "Type": "ALIYUN::ECS::NetworkInterface",
          "Properties": {
            "SecurityGroupId": {
              "Ref": "SecurityGroupId"
            },
            "VSwitchId": {
              "Ref": "VSwitchId"
            },
            "NetworkInterfaceName": "TestNetworkInterface"
          }
        }
      },
      "Outputs": {
        "PrivateIpAddress": {
          "Description": "The primary private ip address of your Network Interface.",
          "Value": {
            "Fn::GetAtt": [
              "EniInstance",
              "PrivateIpAddress"
            ]
          }
        },
        "SecondaryPrivateIpAddresses": {
          "Description": "The secondary private IP addresses of your Network Interface.",
          "Value": {
            "Fn::GetAtt": [
              "EniInstance",
              "SecondaryPrivateIpAddresses"
            ]
          }
        },
        "MacAddress": {
          "Description": "The MAC address of your Network Interface.",
          "Value": {
            "Fn::GetAtt": [
              "EniInstance",
              "MacAddress"
            ]
          }
        },
        "NetworkInterfaceId": {
          "Description": "ID of your Network Interface.",
          "Value": {
            "Fn::GetAtt": [
              "EniInstance",
              "NetworkInterfaceId"
            ]
          }
        }
      }
    }

For more examples, visit NetworkInterfaceAttachment.json and NetworkInterfaceAttachment.yml. In the examples, the following resource types are used: ALIYUN::ECS::NetworkInterface, ALIYUN::ECS::NetworkInterfaceAttachment, and ALIYUN::ECS::NetworkInterfacePermission.