Clarify zuul admin CLI scope

We have two CLIs: zuul-client for REST-related operations, which cover
tenant-scoped, workflow modifying actions such as enqueue, dequeue and
promote; and zuul which supercedes zuul-client and covers also true admin
operations like ZooKeeper maintenance, config checking and issueing auth tokens.
This is a bit confusing for users and operators, and can induce code
duplication.

* Rename zuul CLI into zuul-admin. zuul is still a valid endpoint
  and will be removed after next release.
* Print a deprecation warning when invoking the admin CLI as zuul
  instead of zuul-admin, and when running autohold-*, enqueue-*,
  dequeue and promote subcommands. These subcommands will need to be
  run with zuul-client after next release.
* Clarify the scopes and deprecations in the documentation.

Change-Id: I90cf6f2be4e4c8180ad0f5e2696b7eaa7380b411

1 files changed, 126 insertions, 119 deletions

diff --git a/doc/source/client.rst b/doc/source/client.rst
index 0177c7347..08e35b355 100644
--- a/doc/source/client.rst
+++ b/doc/source/client.rst
@@ -1,11 +1,12 @@
-:title: Zuul Client
+:title: Zuul Admin Client
 
-Zuul Client
-===========
+Zuul Admin Client
+=================
 
 Zuul includes a simple command line client that may be used to affect Zuul's
-behavior while running. It must be run on a host with access to Zuul's web
-server.
+behavior while running.
+
+.. note:: For operations related to normal workflow like enqueue, dequeue, autohold and promote, the `zuul-client` CLI should be used instead.
 
 Configuration
 -------------
@@ -13,76 +14,168 @@ Configuration
 The client uses the same zuul.conf file as the server, and will look
 for it in the same locations if not specified on the command line.
 
-The ``webclient`` section is required.
-
-It is also possible to run the client without a configuration file, by using the
-``--zuul-url`` option to specify the base URL of the Zuul web server.
-
-.. note:: Not all commands are available through the REST API.
-
 Usage
 -----
 The general options that apply to all subcommands are:
 
-.. program-output:: zuul --help
+.. program-output:: zuul-admin --help
 
 The following subcommands are supported:
 
+tenant-conf-check
+^^^^^^^^^^^^^^^^^
+
+.. program-output:: zuul-admin tenant-conf-check --help
+
+Example::
+
+  zuul-admin tenant-conf-check
+
+This command validates the tenant configuration schema. It exits '-1' in
+case of errors detected.
+
+create-auth-token
+^^^^^^^^^^^^^^^^^
+
+.. note:: This command is only available if an authenticator is configured in
+          ``zuul.conf``. Furthermore the authenticator's configuration must
+          include a signing secret.
+
+.. program-output:: zuul-admin create-auth-token --help
+
+Example::
+
+    zuul-admin create-auth-token --auth-config zuul-operator --user alice --tenant tenantA --expires-in 1800
+
+The return value is the value of the ``Authorization`` header the user must set
+when querying a protected endpoint on Zuul's REST API.
+
+Example::
+
+    bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFuYWdlc2Yuc2ZyZG90ZXN0aW5zdGFuY2Uub3JnIiwienV1bC50ZW5hbnRzIjp7ImxvY2FsIjoiKiJ9LCJleHAiOjE1Mzc0MTcxOTguMzc3NTQ0fQ.DLbKx1J84wV4Vm7sv3zw9Bw9-WuIka7WkPQxGDAHz7s
+
+export-keys
+^^^^^^^^^^^
+
+.. program-output:: zuul-admin export-keys --help
+
+Example::
+
+  zuul-admin export-keys /var/backup/zuul-keys.json
+
+import-keys
+^^^^^^^^^^^
+
+.. program-output:: zuul-admin import-keys --help
+
+Example::
+
+  zuul-admin import-keys /var/backup/zuul-keys.json
+
+copy-keys
+^^^^^^^^^
+
+.. program-output:: zuul-admin copy-keys --help
+
+Example::
+
+  zuul-admin copy-keys gerrit old_project gerrit new_project
+
+delete-keys
+^^^^^^^^^^^
+
+.. program-output:: zuul-admin delete-keys --help
+
+Example::
+
+  zuul-admin delete-keys gerrit old_project
+
+delete-state
+^^^^^^^^^^^^
+
+.. program-output:: zuul-admin delete-state --help
+
+Example::
+
+  zuul-admin delete-state
+
+delete-pipeline-state
+^^^^^^^^^^^^^^^^^^^^^
+
+.. program-output:: zuul-admin delete-pipeline-state --help
+
+Example::
+
+  zuul-admin delete-pipeline-state tenant pipeline
+
+Deprecated commands
+-------------------
+
+The following commands are deprecated in the zuul-admin CLI, and thus may not be entirely supported in Zuul's current version.
+They will be removed in a future release of Zuul. They can still be performed via the `zuul-client` CLI.
+Please refer to `zuul-client's documentation <https://zuul-ci.org/docs/zuul-client/>`__
+for more details.
+
+In order to run these commands, the ``webclient`` section is required in the configuration file.
+
+It is also possible to run the client without a configuration file, by using the
+``--zuul-url`` option to specify the base URL of the Zuul web server.
+
 Autohold
 ^^^^^^^^
-.. program-output:: zuul autohold --help
+.. program-output:: zuul-admin autohold --help
 
 Example::
 
-  zuul autohold --tenant openstack --project example_project --job example_job --reason "reason text" --count 1
+  zuul-admin autohold --tenant openstack --project example_project --job example_job --reason "reason text" --count 1
 
 Autohold Delete
 ^^^^^^^^^^^^^^^
-.. program-output:: zuul autohold-delete --help
+.. program-output:: zuul-admin autohold-delete --help
 
 Example::
 
-  zuul autohold-delete --id 0000000123
+  zuul-admin autohold-delete --id 0000000123
 
 Autohold Info
 ^^^^^^^^^^^^^
-.. program-output:: zuul autohold-info --help
+.. program-output:: zuul-admin autohold-info --help
 
 Example::
 
-  zuul autohold-info --id 0000000123
+  zuul-admin autohold-info --id 0000000123
 
 Autohold List
 ^^^^^^^^^^^^^
-.. program-output:: zuul autohold-list --help
+.. program-output:: zuul-admin autohold-list --help
 
 Example::
 
-  zuul autohold-list --tenant openstack
+  zuul-admin autohold-list --tenant openstack
 
 Dequeue
 ^^^^^^^
-.. program-output:: zuul dequeue --help
+.. program-output:: zuul-admin dequeue --help
 
 Examples::
 
-    zuul dequeue --tenant openstack --pipeline check --project example_project --change 5,1
-    zuul dequeue --tenant openstack --pipeline periodic --project example_project --ref refs/heads/master
+    zuul-admin dequeue --tenant openstack --pipeline check --project example_project --change 5,1
+    zuul-admin dequeue --tenant openstack --pipeline periodic --project example_project --ref refs/heads/master
 
 Enqueue
 ^^^^^^^
-.. program-output:: zuul enqueue --help
+.. program-output:: zuul-admin enqueue --help
 
 Example::
 
-  zuul enqueue --tenant openstack --trigger gerrit --pipeline check --project example_project --change 12345,1
+  zuul-admin enqueue --tenant openstack --trigger gerrit --pipeline check --project example_project --change 12345,1
 
 Note that the format of change id is <number>,<patchset>.
 
 Enqueue-ref
 ^^^^^^^^^^^
 
-.. program-output:: zuul enqueue-ref --help
+.. program-output:: zuul-admin enqueue-ref --help
 
 This command is provided to manually simulate a trigger from an
 external source.  It can be useful for testing or replaying a trigger
@@ -106,7 +199,7 @@ the jobs, pass the failed tag as the ``ref`` argument and set
 ``newrev`` to the change associated with the tag in the project
 repository (i.e. what you see from ``git show X.Y.Z``)::
 
-  zuul enqueue-ref --tenant openstack --trigger gerrit --pipeline release --project openstack/example_project --ref refs/tags/X.Y.Z --newrev abc123..
+  zuul-admin enqueue-ref --tenant openstack --trigger gerrit --pipeline release --project openstack/example_project --ref refs/tags/X.Y.Z --newrev abc123..
 
 The command can also be used asynchronosly trigger a job in a
 ``periodic`` pipeline that would usually be run at a specific time by
@@ -114,7 +207,7 @@ the ``timer`` driver.  For example, the following command would
 trigger the ``periodic`` jobs against the current ``master`` branch
 top-of-tree for a project::
 
-  zuul enqueue-ref --tenant openstack --trigger timer --pipeline periodic --project openstack/example_project --ref refs/heads/master
+  zuul-admin enqueue-ref --tenant openstack --trigger timer --pipeline periodic --project openstack/example_project --ref refs/heads/master
 
 Another common pipeline is a ``post`` queue listening for ``gerrit``
 merge results.  Triggering here is slightly more complicated as you
@@ -128,7 +221,7 @@ current ``HEAD`` and the prior change, then enqueue the event::
   NEW_REF=$(git rev-parse HEAD)
   OLD_REF=$(git rev-parse HEAD~1)
 
-  zuul enqueue-ref --tenant openstack --trigger gerrit --pipeline post --project openstack/example_project --ref refs/heads/master --newrev $NEW_REF --oldrev $OLD_REF
+  zuul-admin enqueue-ref --tenant openstack --trigger gerrit --pipeline post --project openstack/example_project --ref refs/heads/master --newrev $NEW_REF --oldrev $OLD_REF
 
 Note that zero values for ``oldrev`` and ``newrev`` can indicate
 branch creation and deletion; the source code is the best reference
@@ -138,11 +231,11 @@ for these more advanced operations.
 Promote
 ^^^^^^^
 
-.. program-output:: zuul promote --help
+.. program-output:: zuul-admin promote --help
 
 Example::
 
-  zuul promote --tenant openstack --pipeline gate --changes 12345,1 13336,3
+  zuul-admin promote --tenant openstack --pipeline gate --changes 12345,1 13336,3
 
 Note that the format of changes id is <number>,<patchset>.
 
@@ -163,90 +256,4 @@ ordering.
 If items in independent pipelines are promoted, no jobs will be
 restarted, but their change queues within the pipeline will be
 re-ordered so that they will be processed first and their node request
-priorities will increase.
-
-tenant-conf-check
-^^^^^^^^^^^^^^^^^
-
-.. program-output:: zuul tenant-conf-check --help
-
-Example::
-
-  zuul tenant-conf-check
-
-This command validates the tenant configuration schema. It exits '-1' in
-case of errors detected.
-
-create-auth-token
-^^^^^^^^^^^^^^^^^
-
-.. note:: This command is only available if an authenticator is configured in
-          ``zuul.conf``. Furthermore the authenticator's configuration must
-          include a signing secret.
-
-.. program-output:: zuul create-auth-token --help
-
-Example::
-
-    zuul create-auth-token --auth-config zuul-operator --user alice --tenant tenantA --expires-in 1800
-
-The return value is the value of the ``Authorization`` header the user must set
-when querying a protected endpoint on Zuul's REST API.
-
-Example::
-
-    bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFuYWdlc2Yuc2ZyZG90ZXN0aW5zdGFuY2Uub3JnIiwienV1bC50ZW5hbnRzIjp7ImxvY2FsIjoiKiJ9LCJleHAiOjE1Mzc0MTcxOTguMzc3NTQ0fQ.DLbKx1J84wV4Vm7sv3zw9Bw9-WuIka7WkPQxGDAHz7s
-
-export-keys
-^^^^^^^^^^^
-
-.. program-output:: zuul export-keys --help
-
-Example::
-
-  zuul export-keys /var/backup/zuul-keys.json
-
-import-keys
-^^^^^^^^^^^
-
-.. program-output:: zuul import-keys --help
-
-Example::
-
-  zuul import-keys /var/backup/zuul-keys.json
-
-copy-keys
-^^^^^^^^^
-
-.. program-output:: zuul copy-keys --help
-
-Example::
-
-  zuul copy-keys gerrit old_project gerrit new_project
-
-delete-keys
-^^^^^^^^^^^
-
-.. program-output:: zuul delete-keys --help
-
-Example::
-
-  zuul delete-keys gerrit old_project
-
-delete-state
-^^^^^^^^^^^^
-
-.. program-output:: zuul delete-state --help
-
-Example::
-
-  zuul delete-state
-
-delete-pipeline-state
-^^^^^^^^^^^^^^^^^^^^^
-
-.. program-output:: zuul delete-pipeline-state --help
-
-Example::
-
-  zuul delete-pipeline-state tenant pipeline
+priorities will increase.
\ No newline at end of file