From 6d0b5b68b5a1ebbd1ce3a283029618576d81da1b Mon Sep 17 00:00:00 2001 From: Jamie Lennox Date: Mon, 9 Nov 2015 16:22:10 +1100 Subject: [PATCH] Deprecate individual CLIs in favour of OSC The OpenStack Client has been the suggested way forward for CLI applications now for a few cycles however we remain in a limbo where in some cases we suggest using OpenStack Client and in others we suggest the project CLI. Ratify that the OpenStack client is the recommended CLI for OpenStack projects so that there is a clear direction on this. Change-Id: Icf517986bfc318eb621210383f81366779da5840 --- specs/deprecate-cli.rst | 192 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 specs/deprecate-cli.rst diff --git a/specs/deprecate-cli.rst b/specs/deprecate-cli.rst new file mode 100644 index 0000000..6feb340 --- /dev/null +++ b/specs/deprecate-cli.rst @@ -0,0 +1,192 @@ +========================= +Deprecate Individual CLIs +========================= + +https://blueprints.launchpad.net/+spec/deprecate-clis + +Historically, each service has offered a CLI application that is included with +the python-\*client that provides administrative and user control over the +service. With the popularity of OpenStack Client and the majority of functions +having been implemented there we should look to officially deprecate the +individual CLI applications. + +This does not imply that the entire python-\*client will be deprecated, just +the CLI portion of the library. The python bindings are expected to continue to +work. + +Problem description +=================== + +There is currently no standard workflow for interacting with OpenStack services +on the command line. In the beginning it made sense that there was a nova CLI +for working with nova. As keystone, glance and cinder split out they cloned +novaclient and adapted it to their needs. By the time neutron and the deluge of +big tent services came along there was a clear pattern that each service would +provide a CLI along with their library. + +Given the common base and some strong persuasion there is at least a common +subset of parameters and environment variables that are accepted by all CLI +applications. However as new features come up such as YAML based configuration, +keystone's v3 authentication or SSL handling issues these must be addressed in +each project individually and the way these parameters are handled have +drifted or are supported to various levels. + +This also creates a horrible user experience for those trying to interact with +the CLI as you have to continually switch between different formatting, command +structures, capabilities and requires a deep knowledge of which service is +responsible for different tasks - a pattern we have been trying to break in +favour of a unified OpenStack interface. + +To deal with this the OpenStack client project has now been around for nearly 2 +years. It provides a pluggable way to register CLI tasks and a common place to +fix security and usability issues. + +Proposed change +=============== + +Whilst there has been general support for the OpenStack Client project and +support from individual services (it is the primary/supported CLI for keystone +and several newer services) there is no clear direction on whether our users +should use it or continue using the project specific CLIs. Similarly there is +no clear direction on whether developers should contribute new features in +services to the service specific CLI or to OpenStack client. + +This blueprint proposes that as a community we ratify that OpenStack Client is +to be the default supported CLI application going forward. This will give +services the direction to deprecate the project CLIs and start pushing their +new features to OpenStack Client. It will give our documentation teams the +direction to start using OpenStack Client as the command for setting up +functionality. + +Given that various projects currently have different needs from their CLI I do +not expect that we will be immediately able to deprecate all CLIs. There may be +certain tasks for which there will always need to be a project specific CLI. +The intent of this blueprint initially is not to provide a timeline or force +projects away from their own CLIs. Instead to provide direction to start +deprecating the CLIs for which OpenStack Client already has functionality +compatibility and properly start the process. + +Alternatives +------------ + +We could look at an oslo project that handles the common components of CLI +generation such that we could standardize parameters and handle client creation +in a cross service way. There may be an advantage to doing this anyway as there +will likely always be tools that want to provide a CLI interface to an +OpenStack API that do not belong in OpenStack Client and these should remain +consistent. + +Doing nothing is always an option. OpenStack client is steadily gaining +adoption naturally because it can quickly provide new features across a range +of services and so CLI deprecation may happen naturally over time. However +until then we must duplicate the effort of supporting features in multiple +places. + +Implementation +============== + +As with all OpenStack applications there will have to be a 2 cycle deprecation +period for all these tools. + +There are multiple components to this spec and much of the work required will +have to be performed individually in each of the services and documentation +projects. The intention of this spec is to indicate to projects that this is +the direction of the community so we can figure out the project specific +requirements in those groups. + + +Assignee(s) +----------- + +Primary assignee: + jamielennox + dtroyer + +Work Items +---------- + +- Add a deprecation warning to clients that have OpenStack Client equivalent + functionality. +- Update documentation to use OpenStack Client commands instead of project + specific CLIs (see Documentation Impact). +- Remove CLI components from CLIs after deprecation period complete. + +Service Impact +-------------- + +For most CLI applications we must first start emitting deprecation warnings for +the CLI tools that ship with the deployment libraries. + +For core services most functionality is already present and maintained in the +OpenStack Client repository so they would need to ensure feature parity however +they would typically not require any additional code. + +As part of core functionality OSC currently supports: + +- Nova +- Glance +- Cinder +- Swift +- Neutron +- Keystone + +A number of additional projects have already implemented their CLI as an +OpenStack Client plugin. These projects will not be affected. Projects that +have not created plugins would need to implement a plugin that handles the +features they wish to expose via CLI. + +Services that currently include an OpenStack Client plugin in their repository +include (but not limited to): + +- Zaqar +- Sahara +- Designate + +Documentation impact +-------------------- + +This will be a fairly fundamental change in the way we have communicated with +users to consume openstack and so will require significant documentation +changes. + +This will include (but not limited to): + +- Install Guides +- Admin Guide +- Ops Guide +- CLI Reference can be deprecated or redirected to OpenStack Client + documentation. + +The OpenStack Client is already in use and deployed as a part of most +installations (it is required for keystone). Therefore changes to documentation +would not be dependant on any work happening in the services. The spec attempts +to ratify that this is the correct approach. + +Dependencies +============ + +There have been many required steps to this goal such as os-client-config, +keystoneauth, cliff, stevedore and the work that has already gone into +OpenStack client. We are now at the point where we can move forward with the +change. + +The OpenStack SDK is not listed as a dependency here because it is not +currently a dependency of OpenStack Client. It is intended that when OpenStack +SDK is released it will be consumed by OpenStack Client however that can be +considered an implementation detail. + +History +======= + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - Mitaka + - Introduced + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode