Neutron API reference should explain the intended behavior of port security extension

[Ihar Hrachyshka]

https://docs.openstack.org/api-ref/network/v2/#port-security

The explanation as of the time of writing is as follows:

"The port-security extension adds the port_security_enabled boolean attribute to networks. At the network level, port_security_enabled defines the default value for new ports attached to the network; they will inherit the value of their network’s port_security_enabled unless explicitly set on the port itself. While the default value for port_security_enabled is true, this can be changed by updating the respective network. Note that changing a value of port_security_enabled on a network, does not cascade the value to ports attached to the network."

It explains how the attribute behaves and how it's inherited by ports, but there is no explanation of what the attribute DOES. Does it disable anti-spoofing? Or SGs? Or both? Is the fact that - traditionally - port_security_enabled=false disables both the intent of the API, or it's just a historical fact on how drivers - traditionally - implement the API?

Same problem as to how port level extension is explained: https://docs.openstack.org/api-ref/network/v2/#id53

"The port-security extension adds the port_security_enabled boolean attribute to ports. If a port-security value is not specified during port creation, a port will inherit the port_security_enabled from the network its connected to."

[Ihar Hrachyshka (ihar-hrachyshka)]

Perhaps relevant to the question of the intended behavior is this wiki page: https://wiki.openstack.org/wiki/Neutron/ML2PortSecurityExtensionDriver even though it's not an official document. It says:

"By creating a port security extension flag, it is possible to enable/disable packet filtering."

which - probably! - implies that both anti-spoofing and ACLs are affected by the flag. If so, this should be clarified in api-ref.

[Ihar Hrachyshka (ihar-hrachyshka)]

A separate question here could be - if port security API affects both SGs and anti-spoofing, then wouldn't it make sense to have some API to disable anti-spoofing but not SGs? This question is explored in a separate bug here: https://bugs.launchpad.net/neutron/+bug/1946251