doc: PUT /ports/{port_id} updates selectively

[Eric Fried]

Based on noted usage in Nova [1], it appears as though PUT /v2/ports/{port_id} [2] with a payload like

 { "port":
       "foo": ...,
 }

will update only port.foo on the server, leaving all the other contents of the port untouched.

That is, you can GET-extract-PUT rather than GET-modify-PUT.

I assume (but am not certain) this is restricted to the top-level keys listed in the table in the API reference. So for example, if the port previously looked like

 { "port":
       ...,
       "dns_assignment": {
           "hostname": "myport",
           "ip_address": "20.20.0.4",
           "fqdn": "myport.my-domain.org"
       },
       ...,
 }

and I PUT /v2/ports/{port_id} with

 { "port":
       "dns_assignment": {
           "ip_address": "10.10.0.4",
       },
 }

I will wind up with no "hostname" or "fqdn" in my port.dns_assignment.

I'm also not certain what happens if I send a `null`

 { "port":
       "binding:profile": null
 }

Do I wind up with port.binding:profile == {}, null, or absent?

===================

This bug is to request that the API reference documentation be enhanced to include this information for PUT /v2/ports/{port_id}.

(It's possible that similar principles apply to PUTting other resources as well -- I didn't check -- in which case it may make sense to write a section in the front matter explaining the principle and linking to it from the various operations.)

[1] http://codesearch.openstack.org/?q=%5C.update_port%5C(&i=nope&files=&repos=openstack/nova
[2] https://developer.openstack.org/api-ref/network/v2/?expanded=update-port-detail#update-port

[Chris Dent (cdent)]

It's probably not worth noting that this violates the definition of PUT.

[Slawek Kaplonski (slaweq)]

I checked this case with sending "null" and it ended up with {}, please look:

[10:21:29] vagrant@devstack-ubuntu-ovs:/opt/stack/neutron$ curl -g -i -X PUT http://10.120.0.30/networking/v2.0/ports/d3d2e4b4-d3ca-4990-aa44-0dae17bce7b5 -H "Accept: application/json" -H "Content-Type: application/json" -H "User-Agent: python-neutronclient" -H "X-Auth-Token: $token" -d '{"port": {"binding:profile": null}}'
HTTP/1.1 200 OK
Date: Fri, 12 Jul 2019 08:21:33 GMT
Server: Apache/2.4.29 (Ubuntu)
Content-Type: application/json
Content-Length: 1164
x-openstack-request-id: req-ec1da9dc-f280-4157-b3bc-d44e3616a810
Connection: close

{"port":{"id":"d3d2e4b4-d3ca-4990-aa44-0dae17bce7b5","name":"test","network_id":"8e8f7b14-9e1e-4ff9-b2c8-246724f50574","tenant_id":"ce5659eb5e504ff796b546138874ef6f","mac_address":"fa:16:3e:3d:ff:66","admin_state_up":true,"status":"DOWN","fixed_ips":[{"subnet_id":"207078c9-baee-418c-a71b-323093db99a5","ip_address":"192.168.0.2"}],"device_id":"dhcpf3db79e0-7113-530b-8d71-7cf272128298-8e8f7b14-9e1e-4ff9-b2c8-246724f50574","device_owner":"network:dhcp","allowed_address_pairs":[],"extra_dhcp_opts":[],"security_groups":[],"description":"","binding:vnic_type":"normal","binding:profile":{},"binding:host_id":"devstack-ubuntu-ovs","binding:vif_type":"ovs","binding:vif_details":{"connectivity":"l2","port_filter":true,"ovs_hybrid_plug":false,"datapath_type":"system","bridge_name":"br-int"},"port_security_enabled":false,"qos_policy_id":null,"dns_name":"","dns_assignment":[{"ip_address":"192.168.0.2","hostname":"host-192-168-0-2","fqdn":"host-192-168-0-2.example.org."}],"dns_domain":"","resource_request":null,"tags":[],"created_at":"2019-06-29T21:31:58Z","updated_at":"2019-07-12T08:21[10:21:34] vagrant@devstack-ubuntu-ovs:/opt/stack/neutron$ neutron port-show d3d2e4b4-d3ca-4990-aa44-0dae17bce7b5
neutron CLI is deprecated and will be removed in the future. Use openstack CLI instead.
+-----------------------+---------------------------------------------------------------------------------------------------------------------------+
| Field | Value |
+-----------------------+---------------------------------------------------------------------------------------------------------------------------+
| admin_state_up | True |
| allowed_address_pairs | |
| binding:host_id | devstack-ubuntu-ovs |
| binding:profile | {} |
| binding:vif_details | {"connectivity": "l2", "port_filter": true, "ovs_hybrid_plug": false, "datapath_type": "system", "bridge_name": "br-int"} |
| binding:vif_type | ovs ...

[Eric Fried (efried)]

null -> {} is a fine behavior (unless you think it isn't :P). It should also be documented.

Thanks for looking at this!

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/ussuri
Review: https://review.opendev.org/726053

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/726293

[OpenStack Infra (hudson-openstack)]

Change abandoned by Abhishek Mahajan (<email address hidden>) on branch: stable/ussuri
Review: https://review.opendev.org/726053
Reason: Fix proposed in following review: https://review.opendev.org/726293

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/726293
Committed: https://git.openstack.org/cgit/openstack/neutron-lib/commit/?id=4c2e5ce0d043e5ca8ac1120f961cd1eea9f9e04b
Submitter: Zuul
Branch: master

commit 4c2e5ce0d043e5ca8ac1120f961cd1eea9f9e04b
Author: triveni <email address hidden>
Date: Wed May 6 08:06:19 2020 +0530

    [Docs] Note about port's binding_profile update

    The fix is to document that, if binding profile of a port is updated to
    null using put command then it is treated as {} in response.

    Closes-Bug: #1836263

    Change-Id: I5fe45af8a8075e52d3a196b24fc926343018d8fd