From ba9a3887869ecd4cbed4aeb43c11a3d9493fafa2 Mon Sep 17 00:00:00 2001 From: Goutham Pacha Ravi Date: Thu, 30 Mar 2023 22:55:24 -0700 Subject: [PATCH] Deprecate "manila" CLI client This has been a long time coming; we have finally reached full feature parity and new features have only been permitted in the openstack CLI plugin for a couple of releases now. We're signalling a major version bump for the package with this change. Implements: bp/openstack-client-support Change-Id: I0a72883f1cd8a5ab9df9c349b6876248fe9edee3 --- doc/source/cli/.gitkeep | 0 doc/source/cli/decoder.rst | 19 +++ doc/source/cli/osc/manila.csv | 1 + doc/source/index.rst | 24 ++- doc/source/user/shell.rst | 8 + manilaclient/osc/v2/data/manila.csv | 152 ++++++++++++++++++ manilaclient/shell.py | 27 ++++ ...precate-manila-shell-0061cbcab5d3d75b.yaml | 16 ++ 8 files changed, 240 insertions(+), 7 deletions(-) delete mode 100644 doc/source/cli/.gitkeep create mode 100644 doc/source/cli/decoder.rst create mode 120000 doc/source/cli/osc/manila.csv create mode 100644 manilaclient/osc/v2/data/manila.csv create mode 100644 releasenotes/notes/deprecate-manila-shell-0061cbcab5d3d75b.yaml diff --git a/doc/source/cli/.gitkeep b/doc/source/cli/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/source/cli/decoder.rst b/doc/source/cli/decoder.rst new file mode 100644 index 000000000..2c336df4b --- /dev/null +++ b/doc/source/cli/decoder.rst @@ -0,0 +1,19 @@ +============================= +OpenStackClient Mapping Guide +============================= + +The following is a mapping between the legacy ``manila`` CLI client and +OpenStackClient. Command options are only shown when necessary. + + +.. only:: html + + .. csv-table:: + :widths: 25, 25, 50 + :file: osc/manila.csv + :header-rows: 1 + +.. only:: pdf + + The mapping can be accessed `here `_ diff --git a/doc/source/cli/osc/manila.csv b/doc/source/cli/osc/manila.csv new file mode 120000 index 000000000..a5de41cae --- /dev/null +++ b/doc/source/cli/osc/manila.csv @@ -0,0 +1 @@ +../../../../manilaclient/osc/v2/data/manila.csv \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 16e207e70..bbd0c7f39 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,21 +11,31 @@ Manila API in order to use the manila client. Command-Line Reference ~~~~~~~~~~~~~~~~~~~~~~ -There are two shell implementations supported by python-manilaclient. -The "manila" client supports full feature parity with the manila API: +There are two shell implementations in python-manilaclient. -.. toctree:: - :maxdepth: 2 +.. important:: - user/shell + The legacy "manila" shell client is deprecated as of version ``5.0.0``. + A future version of python-manilaclient may not ship this legacy shell + client. If you rely on it, it is highly recommended that you begin using + the openstack CLI client right away. Refer to the `mapping guide + `_ to help with this transition. -From version 2.0.0, there is a growing support for the OpenStack client. -It does not yet have full feature parity with the manila API: +The "openstack" CLI client intends to be fully compatible with the manila API: .. toctree:: :maxdepth: 1 cli/osc_plugin_cli + cli/decoder + +The legacy "manila" client is deprecated and may not support newer API +features: + +.. toctree:: + :maxdepth: 2 + + user/shell Using the python module ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/user/shell.rst b/doc/source/user/shell.rst index d1b81e10e..13553ae75 100644 --- a/doc/source/user/shell.rst +++ b/doc/source/user/shell.rst @@ -1,6 +1,14 @@ The :program:`manila` shell utility ========================================= +.. important:: + + This shell client is deprecated as of version ``5.0.0``. A future + version of python-manilaclient may not ship this legacy shell client. If + you rely on it, it is highly recommended that you begin using the + openstack CLI client right away. Refer to the `mapping guide + <../cli/decoder.html>`_ to help with this transition. + .. program:: manila .. highlight:: bash diff --git a/manilaclient/osc/v2/data/manila.csv b/manilaclient/osc/v2/data/manila.csv new file mode 100644 index 000000000..9b7781eaf --- /dev/null +++ b/manilaclient/osc/v2/data/manila.csv @@ -0,0 +1,152 @@ +manila command,openstack command,command description +--version,module list,List the client software version +absolute-limits,share limits show --absolute,Print a list of absolute limits for a user +access-allow,share access create,Allow access to a given share +access-deny,share access delete,Deny access to a share +access-list,share access list,Show access list for share +access-metadata,share access set --property or share access unset --property,Set or delete metadata on a share access rule +access-show,share access show,Show details about a NAS share access rule +api-version,versions show --service sharev2,Display the API version information +availability-zone-list,share availability zone list,List all availability zones +create,share create,Creates a new share +credentials,token issue,Show user credentials returned from auth +delete,share delete,Remove one or more shares +endpoints,endpoint list --service sharev2,Discover endpoints that get returned from the authenticate services +extend,share resize,Increases the size of an existing share +extra-specs-list,share type list,Print a list of current 'share types and extra specs' (Admin Only) +force-delete,share delete --force,Attempt force-delete of share regardless of state +list,share list,List NAS shares with filters +manage,share adopt,Manage share not handled by Manila +message-delete,share message delete,Remove one or more messages +message-list,share message list,Lists all messages +message-show,share message show,Show details about a message +metadata,share set --property or share unset --property,Set or delete metadata on a share +metadata-show,share show -c properties,Show metadata of given share +metadata-update-all,,Update all metadata of a share +migration-cancel,share migration cancel,Cancel migration of a given share when copying +migration-complete,share migration complete,Complete migration for a given share +migration-get-progress,share migration show,Get migration progress of a given share when copying +migration-start,share migration start,Migrate share to a new host +pool-list,share pool list,List all backend storage pools known to the scheduler +quota-class-show,share quota show --class,List the quotas for a quota class +quota-class-update,share quota update --class,Update the quotas for a quota class +quota-defaults,share quota show --class default,List the default quotas for a project +quota-delete,share quota delete,Delete quota for a project or project/user or project/share-type +quota-show,share quota show,List the quotas for a project or user or share type +quota-update,share quota set,Update the quotas for a project/user and/or share type +rate-limits,share limits show --rate,Print a list of rate limits for a user +reset-state,share set --status,Explicitly update the state of a share +reset-task-state,share set --task-state,Explicitly update the task state of a share +restore,share restore,Restore one or more shares from recycle bin +revert-to-snapshot,share revert,Revert a share to the specified snapshot +security-service-create,share security service create,Create security service used by project +security-service-delete,share security service delete,Delete one or more security services +security-service-list,share security service list,Get a list of security services +security-service-show,share security service show,Show security service +security-service-update,share security service set,Update security service +service-disable,share service set --disable,Disables 'manila-share' or 'manila-scheduler' services +service-enable,share service set --enable,Enables 'manila-share' or 'manila-scheduler' services +service-list,share service list,List all services +share-export-location-list,share export location list,List export locations of a given share +share-export-location-show,share export location show,Show export location of the share +share-group-create,share group create,Creates a new share group +share-group-delete,share group delete,Delete one or more share groups +share-group-list,share group list,List share groups with filters +share-group-reset-state,share group set --status,Explicitly update the state of a share group +share-group-show,share group show,Show details about a share group +share-group-update,share group set or share group unset,Update a share group +share-group-snapshot-create,share group snapshot create,Creates a new share group snapshot +share-group-snapshot-delete,share group snapshot delete,Remove one or more share group snapshots +share-group-snapshot-list,share group snapshot list,List share group snapshots with filters +share-group-snapshot-list-members,share group snapshot members list,List members of a share group snapshot +share-group-snapshot-reset-state,share group snapshot set --status,Explicitly update the state of a share group snapshot +share-group-snapshot-show,share group snapshot show,Show details about a share group snapshot +share-group-snapshot-update,share group snapshot set or share group snapshot unset,Update a share group snapshot +share-group-type-access-add,share group type access create,Adds share group type access for the given project +share-group-type-access-list,share group type access list,Print access information about a share group type +share-group-type-access-remove,share group type access delete,Removes share group type access for the given project +share-group-type-create,share group type create,Create a new share group type +share-group-type-delete,share group type delete,Delete a specific share group type +share-group-type-key,share group type set --group-specs,Set or unset group_spec for a share group type +share-group-type-list,share group type list,Print a list of available 'share group types' +share-group-type-specs-list,share group type list,Print a list of 'share group types specs' (Admin Only) +share-instance-export-location-list,share instance export location list,List export locations of a given share instance +share-instance-export-location-show,share instance export location show,Show export location for the share instance +share-instance-force-delete,share instance delete,Force-delete the share instance regardless of state +share-instance-list,share instance list,List share instances +share-instance-reset-state,share instance set --status,Explicitly update the state of a share instance +share-instance-show,share instance show,Show details about a share instance +share-network-create,share network create,Create a share network to export shares to +share-network-delete,share network delete,Delete one or more share networks +share-network-list,share network list,Get a list of share networks +share-network-reset-state,share network set --status,Explicitly update the state of a share network +share-network-security-service-add,share network set --security-service,Associate security service with share network +share-network-security-service-add-check,share network set --check-only --new-security-service,Associate security service with share network +share-network-security-service-list,share network show,Get list of security services associated with a given share network +share-network-security-service-remove,share network unset --security-service,Dissociate security service from share network +share-network-security-service-update,share network set --current-security-service --new-security-service,Update a current security service to a new security service +share-network-security-service-update-check,share network set --check-only --current-security-service --new-security-service,Check if a security service update on the share network is supported +share-network-show,share network show,Retrieve details for a share network +share-network-subnet-create,share network subnet create,Add a new subnet into a share network +share-network-subnet-create-check,share network subnet create --check-only,Check if a new subnet can be added to a share network +share-network-subnet-delete,share network subnet delete,Delete one or more share network subnets +share-network-subnet-show,share network subnet show,Show share network subnet +share-network-update,share network set or share network unset,Update share network data +share-replica-create,share replica create,Create a share replica +share-replica-delete,share replica delete,Remove one or more share replicas +share-replica-export-location-list,share replica export location list,List export locations of a share replica +share-replica-export-location-show,share replica export location show,Show details of a share replica's export location +share-replica-list,share replica list,List share replicas +share-replica-promote,share replica promote,Promote specified replica to 'active' replica_state +share-replica-reset-replica-state,share replica set --replica-state,Explicitly update the 'replica_state' of a share replica +share-replica-reset-state,share replica set --status,Explicitly update the 'status' of a share replica +share-replica-resync,share replica resync,Attempt to update the share replica with its 'active' mirror +share-replica-show,share replica show,Show details about a replica +share-server-delete,share server delete,Delete one or more share servers +share-server-details,share server show,Show share server details +share-server-list,share server list,List all share servers +share-server-manage,share server adopt,Manage share server not handled by Manila +share-server-migration-cancel,share server migration cancel,Cancels migration of a given share server when copying +share-server-migration-check,share server migration start --check-only,Check migration compatibility for a share server with desired properties +share-server-migration-complete,share server migration complete,Complete migration for a given share server +share-server-migration-get-progress,share server migration show,Get migration progress of a given share server when copying +share-server-migration-start,share server migration start,Migrate share server to a new host +share-server-reset-state,share server set --status,Explicitly update the state of a share server +share-server-reset-task-state,share server set --task-state,Explicitly update the task state of a share +share-server-show,share server show,Show share server info +share-server-unmanage,share server abandon,Unmanage share server +show,share show,Show details about a NAS share +shrink,share resize,Decreases the size of an existing share +snapshot-access-allow,share snapshot access create,Allow read only access to a snapshot +snapshot-access-deny,share snapshot access delete,Deny access to a snapshot +snapshot-access-list,share snapshot access list,Show access list for a snapshot +snapshot-create,share snapshot create,Add a new snapshot +snapshot-delete,share snapshot delete,Remove one or more snapshots +snapshot-export-location-list,share snapshot export location list,List export locations of a given snapshot +snapshot-export-location-show,share snapshot export location show,Show export location of the share snapshot +snapshot-force-delete,share snapshot delete --force,Attempt force-deletion of one or more snapshots Regardless of the state +snapshot-instance-export-location-list,share snapshot instance export location list,List export locations of a given snapshot instance +snapshot-instance-export-location-show,share snapshot instance export location show,Show export location of the share instance snapshot +snapshot-instance-list,share snapshot instance list,List share snapshot instances +snapshot-instance-reset-state,share snapshot instance set --status,Explicitly update the state of a share snapshot instance +snapshot-instance-show,share snapshot instance show,Show details about a share snapshot instance +snapshot-list,share snapshot list,List all the snapshots +snapshot-manage,share snapshot adopt,Manage share snapshot not handled by Manila +snapshot-rename,share snapshot set --name,Rename a snapshot +snapshot-reset-state,share snapshot set --status,Explicitly update the state of a snapshot +snapshot-show,share snapshot show,Show details about a snapshot +snapshot-unmanage,share snapshot abandon,Unmanage one or more share snapshots +soft-delete,share delete --soft,Soft delete one or more shares +type-access-add,share type access create,Add share type access for the given project +type-access-list,share type access list,Print access information about the given share type +type-access-remove,share type access delete,Remove share type access for the given project +type-create,share type create,Create a new share type +type-delete,share type delete,Delete one or more specific share types +type-key,share type set --extra-specs,Set or unset extra_spec for a share type +type-list,share type list,Print a list of available 'share types' +type-show,share type show,Show share type details +type-update,share type set or share type unset,Update share type name and/or description and/or visibility +unmanage,share abandon,Unmanage share +update,share set or share unset,Rename a share +bash-completion,complete,Print arguments for bash_completion +list-extensions,,List all the os-api extensions that are available diff --git a/manilaclient/shell.py b/manilaclient/shell.py index 4bcd972a3..0fa0aeba8 100644 --- a/manilaclient/shell.py +++ b/manilaclient/shell.py @@ -19,6 +19,7 @@ Command-line interface to the OpenStack Manila API. """ import argparse +import csv import glob from importlib import util as importlib_util import itertools @@ -608,6 +609,32 @@ class OpenStackManilaShell(object): if profile: osprofiler_profiler.init(options.profile) + try: + decoder_path = os.path.abspath( + 'manilaclient/osc/v2/data/manila.csv' + ) + with open(decoder_path) as f: + decoder_data = { + r['manila command']: r['openstack command'] + for r in csv.DictReader(f, skipinitialspace=True) + } + except Exception: + # this is fine + decoder_data = {} + + deprecation_message = ("manila CLI is deprecated and will be removed " + "in the future. Use openstack CLI instead.") + cmd = args.func.__name__.lstrip('do_').replace("_", "-") + if decoder_data and cmd in decoder_data: + deprecation_message = " ".join([ + deprecation_message, + "The equivalent command is \" openstack", + f"{decoder_data[cmd]}", + "\"" + ]) + + print(deprecation_message, file=sys.stderr) + args.func(self.cs, args) if profile: diff --git a/releasenotes/notes/deprecate-manila-shell-0061cbcab5d3d75b.yaml b/releasenotes/notes/deprecate-manila-shell-0061cbcab5d3d75b.yaml new file mode 100644 index 000000000..1e26729c0 --- /dev/null +++ b/releasenotes/notes/deprecate-manila-shell-0061cbcab5d3d75b.yaml @@ -0,0 +1,16 @@ +--- +prelude: > + OpenStackClient is the preferred CLI client supported by this package. + This CLI client has full feature parity to the legacy "manila" CLI client. +upgrade: + - | + Usage of the "manila" CLI client is discouraged in favor of the + "openstack" CLI. The "manila" CLI client will be removed in a future + release. +deprecations: + - | + The "manila" CLI client is now deprecated. The python-manilaclient + package provides an openstack CLI plugin. As a replacement, the + "openstack" CLI must be used. No new features will be added to the + "manila" CLI client. The "manilalient" SDK/python bindings are not + affected by this deprecation.