Updating network ports

PUT /v2.0/ports/{port_id}

Update a network port.

Source: https://docs.openstack.org/api-ref/network/v2/index.html#update-port

Request

Parameters

Name	In	Type	Description
`port_id`	path	string	The ID of the port.
`port`	body	object	A `port` object.
`admin_state_up` (Optional)	body	boolean	The administrative state of the port, which is up (`true`) or down (`false`).
`allowed_address_pairs` (Optional)	body	array	A set of zero or more allowed address pair objects each where address pair object contains `ip_address` and `mac_address`. While `ip_address` is required, `mac_address` is taken from the port if not specified. The value of `ip_address` can be an IP address or a CIDR. A server connected to the port can send a packet with the source address that matches one of the specified allowed address pairs.
`binding:host_id` (Optional)	body	string	The ID of the host where the port resides. The default is an empty string.
`binding:profile` (Optional)	body	object	A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking backend. The networking API does not define a specific format of this field. The default is an empty dictionary. If you update it with null then it is treated like `{}` in the response. Since the port-mac-address-override extension, the `device_mac_address` field of `binding:profile` can be used to provide the MAC address of the physical device a direct-physical port is being bound to. If provided, then the `mac_address` field of the port resource will be updated to the MAC from the active binding.
`binding:vnic_type` (Optional)	body	string	The type of the vNIC this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are `normal`, `macvtap`, `direct`, `baremetal`, `direct-physical`, `virtio-forwarder`, `smart-nic`, and `remote-managed`. The type of the actually available vNIC depends on deployments. The default is `normal`.
`data_plane_status` (Optional)	body	string	Status of the underlying data plane of a port.
`device_id` (Optional)	body	string	The ID of the device that uses this port. For example, a server instance or a logical router.
`device_owner` (Optional)	body	string	The entity type that uses this port. For example, `compute:nova` (server instance), `network:dhcp` (DHCP agent), or `network:router_interface` (router interface).
`dns_domain` (Optional)	body	string	A valid DNS domain.
`dns_name` (Optional)	body	string	A valid DNS name.
`extra_dhcp_opts` (Optional)	body	array	A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.
`fixed_ips` (Optional)	body	array	The IP addresses for the port. If you would like to assign multiple IP addresses to the port, specify multiple entries in this field. Each entry consists of an IP address (`ip_address`) and the subnet ID from which the IP address is assigned (`subnet_id`). If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the IP address on that subnet to the port. If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify only an IP address, OpenStack Networking tries to allocate the IP address if the address is a valid IP for any of the subnets on the specified network.
`hints` (Optional)	body	object	Admin-only. A dict, at the top level keyed by mechanism driver aliases (as defined in setup.cfg). To following values can be used to control Open vSwitch’s Userspace Tx packet steering feature: `{"openvswitch": {"other_config": {"tx-steering": "hash"}}}` `{"openvswitch": {"other_config": {"tx-steering": "thread"}}}` If omitted, the default is defined by Open vSwitch. The field cannot be longer than 4095 characters.
`mac_address` (Optional)	body	string	The MAC address of the port. If unspecified, a MAC address is generated automatically.
`name` (Optional)	body	string	Human-readable name of the port.
`numa_affinity_policy` (Optional)	body	string	The port NUMA affinity policy requested during the virtual machine scheduling. Values: `none`, `required`, `preferred`, or `legacy`.
`port_security_enabled` (Optional)	body	boolean	The port security status. Valid values are enabled (`true`) and disabled (`false`). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.
`qos_policy_id` (Optional)	body	string	The QoS policy associated with the port.
`security_groups` (Optional)	body	array	The IDs of security groups applied to the port.
`propagate_uplink_status` (Optional)	body	boolean	The uplink status propagation of the port. Valid values are enabled (`true`) and disabled (`false`).
`description` (Optional)	body	string	A human-readable description for the port. Default is an empty string.
`mac_learning_enabled` (Optional)	body	boolean	A boolean value that indicates if MAC Learning is enabled on the associated port.
`port_trusted_vif` (Optional)	body	boolean	The port’s trusted VIF status. A valid value is `true` or `false`. Value of this field is included in the `binding:profile` dict of the port.

Example

# curl -ks -X PUT -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "port": {
    "name": "private-vm-port",
    "device_owner": "compute:nova",
    "device_id": "8bfc5039-e970-40af-94ba-34b774da37ef"
  }
}' https://<node_IP_addr>:9696/v2.0/ports/c85ae844-9ff5-4866-97da-546c3bf0144b

Response

Parameters

Name	In	Type	Description
`port`	body	object	A `port` object.
`admin_state_up`	body	boolean	The administrative state of the port, which is up (`true`) or down (`false`).
`allowed_address_pairs`	body	array	A set of zero or more allowed address pair objects each where address pair object contains `ip_address` and `mac_address`. While `ip_address` is required, `mac_address` is taken from the port if not specified. The value of `ip_address` can be an IP address or a CIDR. A server connected to the port can send a packet with the source address that matches one of the specified allowed address pairs.
`binding:host_id`	body	string	The ID of the host where the port resides.
`binding:profile`	body	object	A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking backend. The networking API does not define a specific format of this field. If the update request is null this response field will be `{}`.
`binding:vif_details`	body	object	A dictionary that contains additional information on the port. Currently the following fields are defined: `port_filter` and `ovs_hybrid_plug`. `port_filter` is a boolean used to indicate if the networking service provides such port filtering features as security group and/or anti MAC/IP spoofing. `ovs_hybrid_plug` is a boolean used to inform an API consumer, like nova, that the hybrid plugging strategy for OVS should be used.
`binding:vif_type`	body	string	The type of the mechanism that is used for the port. An API consumer like Nova can use this to determine an appropriate way to attach a device (for example, a VM interface) to the port. Available values currently defined include `ovs`, `bridge`, `macvtap`, `hw_veb`, `hostdev_physical`, `vhostuser`, `distributed`, and `other`. There are also special values: `unbound` and `binding_failed`. `unbound` means the port is not bound to a networking backend. `binding_failed` means that the port failed to be bound to a networking backend.
`binding:vnic_type`	body	string	The type of the vNIC this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are `normal`, `macvtap`, `direct`, `baremetal`, `direct-physical`, `virtio-forwarder`, `smart-nic`, and `remote-managed`. The type of the actually available vNIC depends on deployments.
`created_at`	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, `2015-08-27T09:49:58-05:00`. The `±hh:mm` value, if included, is the time zone as an offset from UTC. In this example, the offset value is `-05:00`.
`data_plane_status`	body	string	The status of the underlying data plane of the port.
`device_id`	body	string	The ID of the device that uses this port. For example, a server instance or a logical router.
`device_owner`	body	string	The entity type that uses this port. For example, `compute:nova` (server instance), `network:dhcp` (DHCP agent), or `network:router_interface` (router interface).
`dns_assignment`	body	object	Data assigned to a port by the networking internal DNS including the `hostname`, `ip_address`, and `fqdn`.
`dns_domain`	body	string	A valid DNS domain.
`id`	body	string	The ID of the port.
`dns_name`	body	string	A valid DNS name.
`extra_dhcp_opts`	body	array	A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.
`fixed_ips`	body	array	The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of an IP address (`ip_address`) and the subnet ID from which the IP address is assigned (`subnet_id`).
`hints`	body	object	Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature: `{"openvswitch": {"other_config": {"tx-steering": "hash\|thread"}}}`
`ip_allocation`	body	string	Indicates whether the port uses `deferred`, `immediate`, or no IP allocation (`none`).
`mac_address`	body	string	The MAC address of the port. If the port uses the `direct-physical` `vnic_type`, the value of this field is overwritten with the MAC address provided in the active `binding:profile` if any.
`network_id`	body	string	The ID of the attached network.
`numa_affinity_policy` (Optional)	body	string	The port NUMA affinity policy requested during the virtual machine scheduling. Values: `none`, `required`, `preferred`, or `legacy`.
`port_security_enabled`	body	boolean	The port security status. Valid values are enabled (`true`) and disabled (`false`). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.
`project_id`	body	string	The ID of the project.
`qos_network_policy_id`	body	string	The ID of the QoS policy of the network where this port is plugged.
`qos_policy_id`	body	string	The ID of the QoS policy associated with the port.
`revision_number`	body	integer	The revision number of the port.
`resource_request` (Optional)	body	object	Expose Placement resources (for example, `minimum-bandwidth`) and traits (for example, `vnic-type`, `physnet`) requested by a port to Nova and Placement. A `resource_request` object contains the `request_groups` and `same_subtree` keys. `request_groups` is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain the `id`, `required`, and `resources` keys. The `id` field is a string which represents a unique UUID that is generated for each group by combining `port_id` and UUIDs of the QoS rules contributing to the group via the UUID5 method. The `required` key contains the traits (generated from `vnic_type` and `physnet`) required by the port, and the `resources` key contains a mapping of the requested resource class name and requested amount from the QoS policy. The `same_subtree` key contains a list of `id` values from every resource group.
`security_groups`	body	array	The IDs of security groups applied to the port.
`status`	body	string	The port status. Values are `ACTIVE`, `DOWN`, `BUILD` or `ERROR`.
`tenant_id`	body	string	The ID of the project.
`updated_at`	body	string	The date and time when the resource was updated. If the resource has not been updated, this field will be `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, `2015-08-27T09:49:58-05:00`. The `±hh:mm` value, if included, is the time zone as an offset from UTC. In this example, the offset value is `-05:00`.
`propagate_uplink_status`	body	boolean	The uplink status propagation of the port. Valid values are enabled (`true`) and disabled (`false`).
`description`	body	string	A human-readable description for the port.
`mac_learning_enabled` (Optional)	body	boolean	A boolean value that indicates if MAC Learning is enabled on the associated port.
`port_trusted_vif`	body	boolean	The port’s trusted VIF status. A valid value is `true` or `false`. The value of this field is included in the `binding:profile` dict of the port.
`tags`	body	array	The list of tags on the port.

Status codes

Success

Code	Reason
`200 - OK`	Request was successful.

Error

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.
`412 - Precondition Failed`	The server does not meet one of the preconditions that the requester put on the request header fields.

Example

{
  "port": {
    "id": "c85ae844-9ff5-4866-97da-546c3bf0144b",
    "name": "private-vm-port",
    "network_id": "cfbb5d6e-aa97-4efd-8a74-30597027fc8d",
    "tenant_id": "8bf97a9e3b8c41ac9a6722503544941d",
    "mac_address": "fa:16:3e:3a:74:d9",
    "admin_state_up": true,
    "status": "DOWN",
    "device_id": "8bfc5039-e970-40af-94ba-34b774da37ef",
    "device_owner": "compute:nova",
    "fixed_ips": [
      {
        "subnet_id": "66031a48-8534-4b64-a578-533d865fe174",
        "ip_address": "192.168.128.232"
      }
    ],
    "allowed_address_pairs": [
      {
        "mac_address": "fa:14:2a:b3:cb:f0",
        "ip_address": "192.168.128.100"
      }
    ],
    "extra_dhcp_opts": [],
    "security_groups": [
      "2852b920-8106-4e9f-9298-c96356a9cc0a"
    ],
    "description": "",
    "binding:vnic_type": "normal",
    "binding:profile": {},
    "binding:host_id": "",
    "binding:vif_type": "unbound",
    "binding:vif_details": {},
    "port_security_enabled": true,
    "qos_policy_id": null,
    "qos_network_policy_id": null,
    "resource_request": null,
    "tags": [],
    "created_at": "2024-11-18T19:37:20Z",
    "updated_at": "2024-11-21T11:08:58Z",
    "revision_number": 3,
    "project_id": "8bf97a9e3b8c41ac9a6722503544941d"
  }
}