Help Center/ ModelArts/ API Reference/ Lite Server/ Attaching a NIC to a Lite Server
Updated on 2026-11-12 GMT+08:00

Attaching a NIC to a Lite Server

Function

This API is used to attach NICs to a specified Lite Server instance. This API applies to scenarios such as expanding server network capabilities, separating workload and management networks, and building highly available network architectures. In these scenarios, you can use this API to attach additional NICs to a Lite Server. The following prerequisites must be met before using this API: the Lite Server instance must already exist and be in either the running or stopped state; the target network interface must be available and not in use by another instance; the NIC and the server must be in the same AZ; and you must have the required permissions. After the attachment operation is complete, the NIC will be successfully attached to the server. Once the server is started, it can detect and use the new NIC.

Constraints

Only supernode-related resources are supported.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    modelarts:devserver:attachPort

    Write

    devserver *

    -

    -

    -

URI

POST /v1/{project_id}/dev-servers/{id}/attach-ports

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition: Project ID. For details, see Obtaining a Project ID and Name.

Constraints: N/A

Range: 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A

id

Yes

String

Definition: DevServer instance ID.

Constraints: Mandatory.

Range: 1 to 64 characters.

Default Value: N/A.

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

port_id

No

String

Definition: NIC ID. If this parameter is specified, an existing NIC is attached. In this case, other parameters are not required.

Constraints: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Range: N/A

Default Value: N/A

name

No

String

Definition: NIC name.

Constraints: N/A

Range: The value can contain up to 255 characters. This parameter is left blank by default.

Default Value: N/A

network_id

No

String

Definition: Subnet ID of the port.

Constraints: If the port_id parameter is not specified, you need to create a NIC for attachment. In this case, the network_id parameter is mandatory.

Range: The value must be a string in UUID format.

Default Value: N/A

ip_address

No

String

Definition: IP address of the port.

Constraint: The value cannot be updated.

Range: CIDR block.

Default Value: N/A

security_groups

No

Array of strings

Definition: ID list of associated security groups.

Constraints: A port supports a maximum of 100 security groups by default.

Default Value: N/A

enable_efi

No

Boolean

Definition: Whether to enable EFI.

Constraints: N/A

Range:

  • true: EFI is enabled.

  • false: EFI is not enabled.

Default Value: N/A

efi_protocol

No

String

Definition: EFI protocol.

Constraints: N/A

Range: 1 to 64 characters

Default Value: N/A

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

mac_addr

String

Definition: MAC address of the port, which is allocated by the system.

port_id

String

Definition: NIC ID.

Range: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.

port_state

String

Definition: Port status.

Range:

  • ACTIVE: The port is active and can be used for communications.

  • BUILD: The port is being created or configured.

  • DOWN: The port is inactive and cannot be used for communications.

virsubnet_id

String

Definition: ID of the subnet where the port is located.

Range: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.

Example Requests

POST https://{endpoint}/v1/{project_id}/dev-servers/{id}/attach-ports

{
  "name" : "uboe_1209",
  "network_id" : "2ef6878e-0cf8-479e-b15d-e8e5b64c9642",
  "security_groups" : [ "dbc7c0e3-1010-4d7f-9018-3ec7198d450d" ],
  "enable_efi" : true,
  "efi_protocol" : "UBoE"
}

Example Responses

Status code: 200

{
  "mac_addr" : "fa:16:3e:b1:a1:01",
  "port_id" : "e461f141-75df-4fac-903c-0831b1079123",
  "port_state" : "ACTIVE",
  "virsubnet_id" : "2ef6878e-0cf8-479e-b15d-e8e5b64c9642"
}

Status Codes

Status Code

Description

200

OK

Error Codes

See Error Codes.