extension commands and options should be marked

[Akihiro Motoki]

Subcommands and options introduced by an extension should be marked.

For example, port-create --security-group option and security-group-* subcommands are specific to security group extension.
The same thing is applied to other extensions (router, quota, ...)

Since descriptions in the subcommand list displayed by "quantum --help" become long, it is better to introduce categories of subcommands and extension-specific notes should be added to corresponding categories.

[dan wendlandt (danwent)]

Yeah, I'd really like to see a good solution here, such as having help actually check what extensions are enabled on the currently configured quantum server, and only show those options. Otherwise, we're going to have a mess of things exposed in help that the user can't do.

The only problem I see with pinging the server is that we need to be able to print some help text even if the server is unreachable. I guess we could fall back to printing a warning and show all options regardless of extension.

I'm adding Yong and Mark to get their thoughts.

[dan wendlandt (danwent)]

Note: I think we've raise this point before, so there may be a bug on this already.

[yong sheng gong (gongysh)]

I think to show related marks is enough. If user uses the marked commands or options, and they does not work, he should understand it by quantum ext-list command and get to know server does not support the extension. Let quantum Cli connect
to server is a solution, but to show different help information in different kind of situation seemingly makes thing complex and sometimes confusing.

THe marks should look like below (see [ext. xxx] after commands or options]:
gongysh@gongysh-laptop:~$ quantum -h
usage: quantum [--version] [-v] [-q] [-h] [--debug]
               [--os-auth-strategy <auth-strategy>] [--os-auth-url <auth-url>]
               [--os-tenant-name <auth-tenant-name>]
               [--os-username <auth-username>] [--os-password <auth-password>]
               [--os-region-name <auth-region-name>] [--os-token <token>]
               [--os-url <url>]

Command-line interface to the Quantum APIs

optional arguments:
  --version show program's version number and exit
  -v, --verbose Increase verbosity of output. Can be repeated.
  -q, --quiet suppress output except warnings and errors
  -h, --help show this help message and exit
  --debug show tracebacks on errors
  --os-auth-strategy <auth-strategy>
                        Authentication strategy (Env: OS_AUTH_STRATEGY,
                        default keystone). For now, any other value will
                        disable the authentication
  --os-auth-url <auth-url>
                        Authentication URL (Env: OS_AUTH_URL)
  --os-tenant-name <auth-tenant-name>
                        Authentication tenant name (Env: OS_TENANT_NAME)
  --os-username <auth-username>
                        Authentication username (Env: OS_USERNAME)
  --os-password <auth-password>
                        Authentication password (Env: OS_PASSWORD)
  --os-region-name <auth-region-name>
                        Authentication region name (Env: OS_REGION_NAME)
  --os-token <token> Defaults to env[OS_TOKEN]
  --os-url <url> Defaults to env[OS_URL]

Commands for API v2.0:
  ext-list List all exts.
  ext-show Show information of a given resource
  floatingip-associate Create a mapping between a floating ip and a fixed ip. [ext. router]
  floatingip-create Create a floating ip for a given tenant. [ext. router]
  floatingip-delete Delete a given floating ip. [ext. router]
  floatingip-disassociate Remove a mapping from a floating ip to a fixed ip. [ext. router]
  floatingip-list List floating ips that belong to a given tenant. [ext. router]
  floatingip-show Show information of a given floating ip. [ext. router]
  help print detailed help for another command
  l3-agent-add-router Add a router to a L3 agent. [ext. router]
  l3-agent-list List L3 agents hosting a router. [ext. router]
  l3-agent-remove-router Remove a router from a L3 agent. [ext. router]
  net-create Create a network for a given tenant.
  net-delete Delete a given network.
  net-dhcp-agent-list ...

[Akihiro Motoki (amotoki)]

How about grouping commands into sections?
If extension alias listed in ext-list is included in a section title, a user can easily know which commands are available.

Core Features:
  ext-list List all exts.
  ext-show Show information of a given resource
  net-create Create a network for a given tenant.
  net-delete Delete a given network.
  net-external-list List external networks that belong to a given tenant
  net-list List networks that belong to a given tenant.
  net-show Show information of a given network.
  net-update Update network's information.
  port-create Create a port for a given tenant.
  port-delete Delete a given port.
  port-list List ports that belong to a given tenant.
  port-show Show information of a given port.
  port-update Update port's information.
  subnet-create Create a subnet for a given tenant.
  subnet-delete Delete a given subnet.
  subnet-list List networks that belong to a given tenant.
  subnet-show Show information of a given subnet.
  subnet-update Update subnet's information.

Quota Extension:
  quota-delete Delete defined quotas of a given tenant.
  quota-list List defined quotas of all tenants.
  quota-show Show quotas of a given tenant
  quota-update Define tenant's quotas not to use defaults.

Layer-3 Extension:
  floatingip-associate Create a mapping between a floating ip and a fixed ip.
  floatingip-create Create a floating ip for a given tenant.
  floatingip-delete Delete a given floating ip.
  floatingip-disassociate Remove a mapping from a floating ip to a fixed ip.
  floatingip-list List floating ips that belong to a given tenant.
  floatingip-show Show information of a given floating ip.
  router-create Create a router for a given tenant.
  router-delete Delete a given router.
  router-gateway-clear Remove an external network gateway from a router.
  router-gateway-set Set the external network gateway for a router.
  router-interface-add Add an internal network interface to a router.
  router-interface-delete Remove an internal network interface from a router.
  router-list List routers that belong to a given tenant.
  router-port-list List ports that belong to a given tenant, with specified router
  router-show Show information of a given router.
  router-update Update router's information.

Security Gruop Extension:
  security-group-create Create a security group.
  security-group-delete Delete a given security group.
  security-group-list List security groups that belong to a given tenant.
  security-group-rule-create Create a security group rule.
  security-group-rule-delete Delete a given security group rule.
  security-group-rule-list List secur...

[dan wendlandt (danwent)]

A couple concerns:

Associating a command with an extension name does not tell the user a very important fact: whether they can use the command against the server that they are currently hitting.

A second point is that it seems like people are assuming that each command maps to an extension. The reality is that is may be a particular option of a command (e.g., an additional value you can pass when creating a port) that is the extension. How would we represent that?

Showing help that is specific to the extensions currently running on the server is the only way I can think of that achieves both of the above (though there may be others as well).

I agree that it is a bit strange to have "help" for the quantum utility potentially be different against different services, but its somewhat similar to using different versions of the utility (which makes SOME sense, given that you are effectively using different versions of the server).

Definitely open to other ideas though.

[Akihiro Motoki (amotoki)]

I agree that the only way to display supported commands and options is to query the quantum server which extensions are enabled now.

quantum client supports multiple version of Quantum (Folsom, Grizzly, ...) and Quantum features are different among versions. So It is important to display only supported commands from the point of view to avoid users' confusion.
# I was asked from my colleagues multiple times: "Does Folsom version of Quantum support
# securitygroups? security groups subcommands are available in quantum command." :-(

I am wondering what is a good solution.

[Akihiro Motoki (amotoki)]

It is a long living bug I filed.
It sounds reasonable to retrieve the extension list from the server to know which features are available.

There are related bugs like bug 1496748.

[Reedip (reedip-banerjee-deactivatedaccount)]

I would like to take this up , and have a discussion regarding the same.
As a similar bug ( bug 1496748) exists( logged by me) , it would be easier to track both of them together as a single entity

[Reedip (reedip-banerjee-deactivatedaccount)]

Also solves https://bugs.launchpad.net/python-neutronclient/+bug/1418240

[OpenStack Infra (hudson-openstack)]

Change abandoned by Armando Migliaccio (<email address hidden>) on branch: master
Review: https://review.openstack.org/225062

[Akihiro Motoki (amotoki)]

The bug has been open over years and we don't have a good solution on this so far. Neutron CLI is now deprecated and I believe it is reasonable to mark it as Won't Fix.