Add port-mac-address-override shim extension

The neutron patch Ib0638f5db69cb92daf6932890cb89e83cf84f295 introduces a
way to provide a MAC address for a direct-physical port at binding time.
So this patch adds an API extension and document the new behavior in the API ref.

Related-Bug: #1942329
Change-Id: I54b4c85ffc4856fba7ad5e9e29f77f74815e1275

api-ref/source/v2/parameters.yaml

@@ -2657,6 +2657,11 @@ binding:profile-request:
     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 the 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.
   in: body
   required: false
   type: object
@@ -4554,7 +4559,9 @@ logs:
   type: array
 mac_address:
   description: |
-    The MAC address of the port.
+    The MAC address of the port. If the port uses the ``direct-physical``
+    ``vnic_type`` then the value of this field is overwritten with the MAC
+    address provided in the active binding:profile if any.
   in: body
   required: true
   type: string

neutron_lib/api/definitions/__init__.py

@@ -85,6 +85,7 @@ from neutron_lib.api.definitions import network_segment_range
 from neutron_lib.api.definitions import pagination
 from neutron_lib.api.definitions import port
 from neutron_lib.api.definitions import port_device_profile
+from neutron_lib.api.definitions import port_mac_address_override
 from neutron_lib.api.definitions import port_mac_address_regenerate
 from neutron_lib.api.definitions import port_numa_affinity_policy
 from neutron_lib.api.definitions import port_resource_request
@@ -228,6 +229,7 @@ _ALL_API_DEFINITIONS = {
     pagination,
     port,
     port_device_profile,
+    port_mac_address_override,
     port_mac_address_regenerate,
     port_numa_affinity_policy,
     port_resource_request,

neutron_lib/api/definitions/base.py

@@ -135,6 +135,7 @@ KNOWN_EXTENSIONS = (
     'network-segment-range',
     'network_availability_zone',
     'pagination',
+    'port-mac-address-override',
     'port-resource-request',
     'port-security',
     'project-id',

neutron_lib/api/definitions/port_mac_address_override.py

@@ -0,0 +1,30 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+NAME = 'Neutron Port MAC address override'
+ALIAS = 'port-mac-override'
+DESCRIPTION = (
+    "Allow overriding the MAC address of a direct-physical Port via the "
+    "active binding profile")
+
+UPDATED_TIMESTAMP = "2022-03-18T10:00:00-00:00"
+
+RESOURCE_ATTRIBUTE_MAP = {}
+
+IS_SHIM_EXTENSION = True
+IS_STANDARD_ATTR_EXTENSION = False
+SUB_RESOURCE_ATTRIBUTE_MAP = {}
+ACTION_MAP = {}
+REQUIRED_EXTENSIONS = []
+OPTIONAL_EXTENSIONS = []
+ACTION_STATUS = {}

releasenotes/notes/add-port-mac-address-override-shim-extension-fb11c4f40c12a99b.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Add API extension ``port-mac-address-override``. This is a shim extension
+    that indicates if Neutron supports overriding the direct-phyiscal port MAC
+    via the active binding profile.