[openstack-dev] [nova] nova networking API and CLI are poorly documented and buggy

Mike Spreitzer mspreitz at us.ibm.com
Tue Jun 17 06:26:05 UTC 2014

I am not even sure what is the intent, but some of the behavior looks like 

it is clearly unintended and not useful (i.e., buggy).

IMHO, the API and CLI documentation should explain these calls/commands in 

enough detail that the reader can tell the difference.  And the difference 

should be useful in at least some networking configurations.  It seems to 
me that in some configurations an administrative user may want THREE 
varieties of the network listing call/command: one that shows networks 
assigned to his tenant, one that also shows networks available to be 
assigned, and one that shows all networks.  And in no configurations 
should a non-administrative user be blind to all categories of networks.

In the API, there are the calls on /v2/{tenant_id}/os-networks and they 
are documented at 

.  There are also calls on /v2/{tenant_id}/os-tenant-networks --- but I 
can not find documentation for them.


does not describe the meaning of the calls in much detail.  For example, 
about "GET /v2/{tenant_id}/os-networks" that doc says only "Lists networks 

that are available to the tenant".  In some networking configurations, 
there are two levels of availability: a network might be assigned to a 
tenant, or a network might be available for assignment.  In other 
networking configurations there are NOT two levels of availability.  For 
example, in Flat DHCP nova networking (which is the default in DevStack), 
a network CAN NOT be assigned to a tenant.

You might think that the "to the tenant" qualification implies filtering 
by the invoker's tenant.  But you would be wrong in the case of an 
administrative user; see the model_query method in 

In the CLI, we have two sets of similar-seeming commands.  For example,

$ nova help net-list
usage: nova net-list

List networks

$ nova help network-list
usage: nova network-list

Print a list of available networks.

Those remarks are even briefer than the one description in the API doc, 
omitting the qualification "to the tenant".

Experimentation shows that, in the case of flat DHCP nova networking, both 

of those commands show zero networks to a non-administrative user (and 
remember that networks can not be assigned to tenants in that 
configuration) and all the networks to an administrative user.  At the API 

the GET calls behave the same way.  The fact that a non-administrative 
user sees zero networks looks unintended and not useful.

See https://bugs.launchpad.net/openstack-manuals/+bug/1152862 and 

Can anyone tell me why there are both /os-networks and /os-tenant-networks 

calls and what their intended semantics are?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140617/f09f2a09/attachment.html>

More information about the OpenStack-dev mailing list