Chuyển tới nội dung chính

Tạo network port

POST/v2.0/ports

Tạo network port trên một mạng được chỉ định.

Theo policy mặc định, bạn chỉ có thể tạo port trên các mạng thuộc project của mình (trừ khi bạn có quyền admin).

Request​

Cấu trúc body​

Object JSON cấp cao nhất phải chứa một object port duy nhất với các thuộc tính bên dưới.

Tham số​

portobjectbắt buộc

Object port (container cho tất cả thuộc tính bên dưới).

admin_state_upboolean

Trạng thái quản trị của port: up (true) hoặc down (false). Mặc định: true.

allowed_address_pairsarray

Không hoặc nhiều object, mỗi object có ip_address (bắt buộc) và mac_address tuỳ chọn. ip_address có thể là một IP hoặc CIDR. Nếu bỏ qua mac_address, mặc định dùng MAC của port. Cho phép server gửi packet với các địa chỉ nguồn đó.

binding:host_idstring

ID của host nơi port nên nằm.

binding:profileobject

Dict không định dạng cho thông tin VIF đặc thù backend. Dùng device_mac_address khi bind port direct-physical để ghi đè MAC. Mặc định là object rỗng {}.

binding:vnic_typestring

Loại vNIC mong muốn. Một trong: normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic, remote-managed. Mặc định: normal.

device_idstring

ID của thiết bị (ví dụ server instance hoặc router) sẽ dùng port này.

device_ownerstring

Loại entity sử dụng port (ví dụ compute:nova, network:dhcp, network:router_interface).

dns_domainstring

DNS domain hợp lệ cần liên kết.

dns_namestring

DNS name (hostname) hợp lệ cần liên kết.

extra_dhcp_optsarray

Không hoặc nhiều object DHCP option (opt_name, opt_value).

fixed_ipsarray

Gán IP cụ thể. Mỗi phần tử có thể gồm subnet_id và/hoặc ip_address. Cách hoạt động: cung cấp cả hai để yêu cầu một địa chỉ chính xác; chỉ subnet_id để tự động cấp từ subnet đó; chỉ ip_address để cấp nếu hợp lệ trên bất kỳ subnet nào của mạng.

hintsobject

Chỉ admin. Dict theo mechanism driver (ví dụ {"openvswitch": {"other_config": {"tx-steering": "hash"}}}). Độ dài tối đa 4095 ký tự sau khi serialize.

mac_addressstring

Địa chỉ MAC của port. Tự động sinh nếu bỏ qua.

namestring

Tên dễ đọc của port.

network_idstringbắt buộc

ID của mạng cần gắn port. (Bắt buộc)

numa_affinity_policystring

Policy NUMA affinity: none, required, preferred hoặc legacy.

port_security_enabledboolean

Bật (true) hoặc tắt (false) việc áp dụng security group và anti-spoofing. Mặc định theo cấu hình của mạng.

project_idstring

ID project sẽ sở hữu port (chỉ admin / advsvc nếu khác project hiện tại).

qos_policy_idstring

ID QoS policy cần áp dụng.

security_groupsarray

Danh sách ID security group. Nếu bỏ qua, mặc định dùng security group mặc định đã cấu hình của mạng (hoặc không có).

tenant_idstring

Alias deprecated của project_id.

propagate_uplink_statusboolean

Có lan truyền trạng thái uplink hay không (true/false).

descriptionstring

Mô tả dễ đọc. Mặc định: chuỗi rỗng.

mac_learning_enabledboolean

Bật MAC learning trên port.

port_trusted_vifboolean

Trạng thái trusted VIF (true/false). Được phản ánh trong binding:profile.

Request mẫu​

curl -ks -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: gAAAAA<...>' \
     -d '{
    "port": {
        "name": "private-port",
        "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
        "fixed_ips": [
            {
                "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                "ip_address": "192.168.1.12"
            }
        ]
    }
}' \
https://<node_IP_addr>:9696/v2.0/ports

Response​

Tham số response​

Nếu thành công, API trả về một object port duy nhất chứa tài nguyên vừa tạo.

portobjectbắt buộc

Object port.

admin_state_upbooleanbắt buộc

Trạng thái quản trị (true hoặc false).

allowed_address_pairsarraybắt buộc

Allowed address pair (xem phần request).

binding:host_idstringbắt buộc

ID của host nơi port nằm.

binding:profileobjectbắt buộc

Thông tin VIF đặc thù backend (rỗng {} nếu không có).

binding:vif_detailsobjectbắt buộc

Thông tin bổ sung (ví dụ port_filter, ovs_hybrid_plug).

binding:vif_typestringbắt buộc

Loại mechanism driver (ovs, bridge, macvtap, v.v.) hoặc unbound / binding_failed.

binding:vnic_typestringbắt buộc

Loại vNIC được yêu cầu / đang áp dụng.

created_atstringbắt buộc

Thời điểm tạo (ISO 8601).

data_plane_statusstringbắt buộc

Trạng thái data plane bên dưới (tuỳ deployment).

device_idstringbắt buộc

ID của thiết bị được gắn (rỗng nếu chưa có).

device_ownerstringbắt buộc

Loại entity sở hữu.

dns_assignmentobjectbắt buộc

Gán DNS nội bộ (hostname, ip_address, fqdn).

dns_domainstringbắt buộc

DNS domain.

dns_namestringbắt buộc

DNS name.

extra_dhcp_optsarraybắt buộc

Các DHCP option bổ sung được áp dụng.

fixed_ipsarraybắt buộc

Các địa chỉ IP được gán (danh sách {subnet_id, ip_address}).

hintsobjectbắt buộc

Hint điều khiển OVS Userspace Tx packet steering nếu có.

idstringbắt buộc

ID của port.

ip_allocationstringbắt buộc

Chế độ cấp phát (immediate, deferred hoặc none).

mac_addressstringbắt buộc

Địa chỉ MAC (có thể bị binding ghi đè với direct-physical).

namestringbắt buộc

Tên port.

network_idstringbắt buộc

ID mạng.

numa_affinity_policystring

Policy NUMA affinity.

port_security_enabledbooleanbắt buộc

Port security có được bật hay không.

project_idstringbắt buộc

ID project sở hữu.

qos_network_policy_idstringbắt buộc

QoS policy của mạng (nếu có).

qos_policy_idstringbắt buộc

QoS policy áp dụng trực tiếp lên port (nếu có).

revision_numberintegerbắt buộc

Revision number.

resource_requestobject

Các nhóm tài nguyên / trait Placement được yêu cầu.

security_groupsarraybắt buộc

ID security group trên port.

statusstringbắt buộc

Trạng thái port: ACTIVE, DOWN, BUILD hoặc ERROR.

tenant_idstringbắt buộc

ID project (trường legacy).

updated_atstringbắt buộc

Thời điểm cập nhật gần nhất (ISO 8601) hoặc null.

propagate_uplink_statusbooleanbắt buộc

Cờ lan truyền trạng thái uplink.

descriptionstringbắt buộc

Mô tả.

mac_learning_enabledboolean

MAC learning có được bật hay không.

port_trusted_vifbooleanbắt buộc

Trạng thái trusted VIF.

tagsarraybắt buộc

Danh sách tag.

Mã trạng thái​

Thành công​

MãMô tả
201 - CreatedTài nguyên đã được tạo và sẵn sàng sử dụng.

Lỗi​

MãMô tả
400 - Bad RequestNội dung request không hợp lệ.
401 - UnauthorizedCần xác thực trước khi gửi request.
403 - ForbiddenPolicy không cho phép user hiện tại thực hiện thao tác này.
404 - Not FoundKhông tìm thấy tài nguyên được yêu cầu (ví dụ mạng).

Response mẫu​

Response body
{
    "port": {
        "id": "2d74fa0c-3e43-4fd9-a234-cbb4996cc684",
        "name": "private-port",
        "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
        "tenant_id": "f33507157a634f1cac71e06a70fb558e",
        "mac_address": "fa:16:3e:7f:ae:b2",
        "admin_state_up": true,
        "status": "DOWN",
        "device_id": "",
        "device_owner": "",
        "fixed_ips": [
            {
                "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                "ip_address": "192.168.1.12"
            }
        ],
        "project_id": "f33507157a634f1cac71e06a70fb558e",
        "port_security_enabled": true,
        "qos_policy_id": null,
        "security_groups": [
            "e1c1aa83-7302-4493-9cf4-43c2407e8074"
        ],
        "binding:vnic_type": "normal",
        "allowed_address_pairs": [],
        "extra_dhcp_opts": [],
        "description": "",
        "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
        "tags": [],
        "created_at": "2025-10-08T08:05:12Z",
        "updated_at": "2025-10-08T08:05:12Z",
        "revision_number": 1
    }
}

Xem thêm​