Open Stack

I am not even sure what is the intent, but some of the behavior looks like 
it is clearly unintended and not useful (a more precise formulation of 
"buggy" that is not defeated by the lack of documentation).

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 
http://docs.openstack.org/api/openstack-compute/2/content/ext-os-networks.html
.  There are also calls on /v2/{tenant_id}/os-tenant-networks --- but I 
can not find documentation for them.

http://docs.openstack.org/api/openstack-compute/2/content/ext-os-networks.html 
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 
nova/db/sqlalchemy/api.py 

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 
https://bugs.launchpad.net/nova/+bug/1327406

Can anyone tell me why there are both /os-networks and /os-tenant-networks 
calls and what their intended semantics are?

Thanks,
Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140614/dfb001ee/attachment.html>