diff options
Diffstat (limited to 'doc/source/client.rst')
| -rw-r--r-- | doc/source/client.rst | 276 |
1 files changed, 149 insertions, 127 deletions
diff --git a/doc/source/client.rst b/doc/source/client.rst index 98eb517fa..cde18bfff 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,177 @@ 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 + +prune-database +^^^^^^^^^^^^^^ + +.. program-output:: zuul-admin prune-database --help + +Example:: + + zuul-admin prune-database --older-than 180d + +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 +208,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 +216,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 +230,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,109 +240,29 @@ 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>. -The promote action is used to reorder the change queue in a pipeline, by putting -the provided changes at the top of the queue; therefore this action makes the -most sense when performed against a dependent pipeline. - -The most common use case for the promote action is the need to merge an urgent -fix when the gate pipeline has already several patches queued ahead. This is -especially needed if there is concern that one or more changes ahead in the queue -may fail, thus increasing the time to land for the fix; or concern that the fix -may not pass validation if applied on top of the current patch queue in the gate. - -If the queue of a dependent pipeline is targeted by the promote, all the ongoing -jobs in that queue will be canceled and restarted on top of the promoted changes. - -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:: +The promote action is used to reorder the changes in a pipeline, by +putting the provided changes at the top of the queue. - zuul copy-keys gerrit old_project gerrit new_project +The most common use case for the promote action is the need to merge +an urgent fix when the gate pipeline has several patches queued +ahead. This is especially needed if there is concern that one or more +changes ahead in the queue may fail, thus increasing the time to land +for the fix; or concern that the fix may not pass validation if +applied on top of the current patch queue in the gate. -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:: +Any items in a dependent pipeline which have had items ahead of them +changed will have their jobs canceled and restarted based on the new +ordering. - zuul delete-pipeline-state tenant pipeline +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. |