Zuul 관리자 클라이언트 (Zuul Admin Client)
Zuul은 실행 중인 Zuul의 동작을 제어할 수 있는 간단한 커맨드 라인 클라이언트를 포함합니다.
참고
하지만 enqueue, dequeue, autohold, promote와 같은 일반적인 워크플로우 관련 작업에는 zuul-client CLI를 사용해야 합니다.
구성 (Configuration)
클라이언트는 서버와 동일한 zuul.conf 파일을 사용합니다. 커맨드 라인에서 경로를 지정하지 않으면, 서버와 동일한 위치에서 파일을 찾습니다.
사용법 (Usage)
모든 서브커맨드(subcommand)에 공통으로 적용되는 옵션은 다음과 같습니다.
usage: zuul-admin [-h] [-c CONFIG] [--version] [-v] [--auth-token AUTH_TOKEN]
[--zuul-url ZUUL_URL] [--insecure]
{autohold,autohold-delete,autohold-info,autohold-list,enqueue,enqueue-ref,dequeue,promote,show,tenant-conf-check,create-auth-token,import-keys,export-keys,copy-keys,delete-keys,delete-oidc-signing-keys,import-images,export-images,delete-state,delete-pipeline-state,prune-database}
...
Zuul CLI client.
options:
-h, --help show this help message and exit
-c CONFIG specify the config file
--version show zuul version
-v verbose output
--auth-token AUTH_TOKEN
Authentication Token, needed if using theREST API
--zuul-url ZUUL_URL Zuul API URL, needed if using the REST API without a
configuration file
--insecure Do not verify SSL connection to Zuul, when using the
REST API (Defaults to False)
commands:
valid commands
{autohold,autohold-delete,autohold-info,autohold-list,enqueue,enqueue-ref,dequeue,promote,show,tenant-conf-check,create-auth-token,import-keys,export-keys,copy-keys,delete-keys,delete-oidc-signing-keys,import-images,export-images,delete-state,delete-pipeline-state,prune-database}
additional help
autohold [DEPRECATED - use zuul-client] hold nodes for failed
job
autohold-delete [DEPRECATED - use zuul-client] delete autohold request
autohold-info [DEPRECATED - use zuul-client] retrieve autohold
request detailed info
autohold-list [DEPRECATED - use zuul-client] list autohold requests
enqueue [DEPRECATED - use zuul-client] enqueue a change
enqueue-ref [DEPRECATED - use zuul-client] enqueue a ref
dequeue [DEPRECATED - use zuul-client] dequeue a buildset by
its change or ref
promote [DEPRECATED - use zuul-client] promote one or more
changes
show [DEPRECATED - use zuul-client] show current statuses
tenant-conf-check validate the tenant configuration
create-auth-token create an Authentication Token for the web API
import-keys import project keys to ZooKeeper
export-keys export project keys from ZooKeeper
copy-keys copy keys from one project to another
delete-keys delete project keys
delete-oidc-signing-keys
delete OIDC signing keys
import-images import images to ZooKeeper
export-images export images from ZooKeeper
delete-state delete ephemeral ZooKeeper state
delete-pipeline-state
delete single pipeline ZooKeeper state
prune-database prune old database entries
지원하는 서브커맨드는 다음과 같습니다.
tenant-conf-check
usage: zuul-admin tenant-conf-check [-h]
options:
-h, --help show this help message and exit
예제:
zuul-admin tenant-conf-check
이 명령은 테넌트(tenant) 구성 스키마를 검증합니다. 오류가 감지되면 ‘-1’로 종료합니다.
create-auth-token
참고
이 명령은 zuul.conf에 인증자(authenticator)가 구성되어 있는 경우에만 사용할 수 있습니다. 또한, 인증자 구성에는 반드시 서명 시크릿(signing secret)이 포함되어 있어야 합니다.
usage: zuul-admin create-auth-token [-h] --auth-config AUTH_CONFIG
[--tenant TENANT] --user USER
[--expires-in EXPIRES_IN]
[--claim [CLAIM ...]] [--print-meta-info]
Create an Authentication Token for the administration web API
Create a bearer token that can be used to access Zuul's
administration web API. This is typically used to delegate
privileged actions such as enqueueing and autoholding to
third parties, scoped to a single tenant.
At least one authenticator must be configured with a secret
that can be used to sign the token.
options:
-h, --help show this help message and exit
--auth-config AUTH_CONFIG
The authenticator to use. Must match an authenticator
defined in zuul's configuration file.
--tenant TENANT When specified, zuul.admin claim with the value of the
tenant will be added to the token.
--user USER The user's name. Used for traceability in logs.
--expires-in EXPIRES_IN
Token validity duration in seconds (default: 600)
--claim [CLAIM ...] Custom claim in format claim:value. It can be used
multiple times to add multiple claims.
--print-meta-info When specified, the meta info of the token will be
printed
예제:
zuul-admin create-auth-token --auth-config zuul-operator --user alice --tenant tenantA --expires-in 1800 --print-meta-info
반환 값은 Zuul의 REST API에서 보호된 엔드포인트를 쿼리할 때 사용자가 설정해야 하는 Authorization 헤더의 값입니다. –tenant 옵션이 지정되면, 해당 테넌트 값을 가진 zuul.admin 클레임(claim)이 토큰에 추가됩니다. –print-meta-info가 지정되면 토큰의 메타 정보가 출력됩니다.
예제:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NDEzNTAzMTksImV4cCI6MTc0MTM1MjExOSwiaXNzIjoienV1bF9vcGVyYXRvciIsImF1ZCI6Inp1dWwuZXhhbXBsZS5jb20iLCJzdWIiOiJhbGljZSIsInp1dWwiOnsiYWRtaW4iOlsidGVuYW50QSJdfX0.cW3U5LEFJS0TM-EDELZS9_hhbxdw-xObLwvDQKL55fM
---------------- Meta Info ----------------
Tenant: tenantA
User: alice
Generated At: 2025-03-07 12:25:19 UTC
Expired At: 2025-03-07 12:55:19 UTC
SHA1 Checksum: f52018044a209ce7eed5e587c41cc8b360af891d
-------------------------------------------
export-keys
usage: zuul-admin export-keys [-h] path
Export project secret keys from ZooKeeper
This command exports project secret keys from ZooKeeper
and writes them to a file which is suitable for backing
up and later use with the import-keys command.
The key contents are still protected by the keystore
password and can not be used or decrypted without it.
positional arguments:
path key export file path
options:
-h, --help show this help message and exit
예제:
zuul-admin export-keys /var/backup/zuul-keys.json
import-keys
usage: zuul-admin import-keys [-h] [--force] path
Import previously exported project secret keys to ZooKeeper
Given a file with previously exported project keys, this
command will import them into ZooKeeper. Existing keys
will not be overwritten; to overwrite keys, add the
--force flag.
positional arguments:
path key export file path
options:
-h, --help show this help message and exit
--force overwrite existing keys
예제:
zuul-admin import-keys /var/backup/zuul-keys.json
copy-keys
usage: zuul-admin copy-keys [-h]
src_connection src_project dest_connection
dest_project
Copy secret keys from one project to another
When projects are renamed, this command may be used to
copy the secret keys from the current name to the new name
in order to avoid service interruption.
positional arguments:
src_connection original connection name
src_project original project name
dest_connection new connection name
dest_project new project name
options:
-h, --help show this help message and exit
예제:
zuul-admin copy-keys gerrit old_project gerrit new_project
delete-keys
usage: zuul-admin delete-keys [-h] connection project
Delete the ssh and secrets keys for a project
positional arguments:
connection connection name
project project name
options:
-h, --help show this help message and exit
예제:
zuul-admin delete-keys gerrit old_project
delete-oidc-signing-keys
usage: zuul-admin delete-oidc-signing-keys [-h] algorithm
Delete the OIDC signing keys of an algorithm
positional arguments:
algorithm algorithm name
options:
-h, --help show this help message and exit
예제:
zuul-admin delete-oidc-signing-keys RS256
delete-state
usage: zuul-admin delete-state [-h] [--keep-config-cache]
Delete all ephemeral state stored in ZooKeeper
Zuul stores a considerable amount of ephemeral state
information in ZooKeeper. Generally it should be able to
detect and correct any errors, but if the state becomes
corrupted and it is unable to recover, this command may be
used to delete all ephemeral data from ZooKeeper and start
anew.
Do not run this command while any Zuul component is
running (perform a complete shutdown first).
This command will only remove ephemeral Zuul data from
ZooKeeper; it will not remove private keys or Nodepool
data.
options:
-h, --help show this help message and exit
--keep-config-cache keep config cache
예제:
zuul-admin delete-state
delete-pipeline-state
usage: zuul-admin delete-pipeline-state [-h] tenant pipeline
Delete a single pipeline state stored in ZooKeeper
In the unlikely event that a bug in Zuul or ZooKeeper data
corruption occurs in such a way that it only affects a
single pipeline, this command might be useful in
attempting to recover.
The circumstances under which this command will be able to
effect a recovery are very rare and even so it may not be
sufficient. In general, if an error occurs it is better
to shut Zuul down and run "zuul delete-state".
This command will lock the specified tenant and
then completely delete the pipeline state.
positional arguments:
tenant tenant name
pipeline pipeline name
options:
-h, --help show this help message and exit
예제:
zuul-admin delete-pipeline-state tenant pipeline
prune-database
usage: zuul-admin prune-database [-h] [--before BEFORE]
[--older-than OLDER_THAN]
[--batch-size BATCH_SIZE]
Prune old database entries
This command will delete database entries older than the
specified cutoff (which can be specified as either an
absolute or relative time).
options:
-h, --help show this help message and exit
--before BEFORE absolute timestamp (e.g., "2022-01-31 12:00:00")
--older-than OLDER_THAN
relative time (e.g., "24h" or "180d")
--batch-size BATCH_SIZE
transaction batch size
예제:
zuul-admin prune-database --older-than 180d
사용 중단된 명령 (Deprecated commands)
다음 명령들은 zuul-admin CLI에서 사용이 중단되었으며(deprecated), 현재 Zuul 버전에서 완벽하게 지원되지 않을 수 있습니다. 향후 Zuul 릴리스에서 제거될 예정입니다. 해당 작업은 zuul-client CLI를 통해 여전히 수행할 수 있습니다. 자세한 내용은 zuul-client 문서 를 참고하세요.
이 명령들을 실행하려면 구성 파일에 webclient 섹션이 필요합니다.
또한, 구성 파일 없이 zuul-admin 클라이언트를 실행할 수도 있습니다. 이 경우 –zuul-url 옵션을 사용하여 Zuul 웹 서버의 베이스 URL(base URL)을 지정해야 합니다.
Autohold
usage: zuul-admin autohold [-h] --tenant TENANT --project PROJECT --job JOB
[--change CHANGE] [--ref REF] --reason REASON
[--count COUNT]
[--node-hold-expiration NODE_HOLD_EXPIRATION]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--project PROJECT project name
--job JOB job name
--change CHANGE specific change to hold nodes for
--ref REF git ref to hold nodes for
--reason REASON reason for the hold
--count COUNT number of job runs (default: 1)
--node-hold-expiration NODE_HOLD_EXPIRATION
how long in seconds should the node set be in HOLD
status (default: scheduler's default_hold_expiration
value)
예제:
zuul-admin autohold --tenant openstack --project example_project --job example_job --reason "reason text" --count 1
Autohold Delete
usage: zuul-admin autohold-delete [-h] REQUEST_ID
positional arguments:
REQUEST_ID the hold request ID
options:
-h, --help show this help message and exit
예제:
zuul-admin autohold-delete --id 0000000123
Autohold Info
usage: zuul-admin autohold-info [-h] REQUEST_ID
positional arguments:
REQUEST_ID the hold request ID
options:
-h, --help show this help message and exit
예제:
zuul-admin autohold-info --id 0000000123
Autohold List
usage: zuul-admin autohold-list [-h] --tenant TENANT
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
예제:
zuul-admin autohold-list --tenant openstack
Dequeue
usage: zuul-admin dequeue [-h] --tenant TENANT --pipeline PIPELINE --project
PROJECT [--change CHANGE] [--ref REF]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--change CHANGE change id
--ref REF ref name
예제:
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
usage: zuul-admin enqueue [-h] --tenant TENANT [--trigger TRIGGER] --pipeline
PIPELINE --project PROJECT --change CHANGE
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--trigger TRIGGER trigger name (deprecated and ignored. Kept only for
backward compatibility)
--pipeline PIPELINE pipeline name
--project PROJECT project name
--change CHANGE change id
예제:
zuul-admin enqueue --tenant openstack --trigger gerrit --pipeline check --project example_project --change 12345,1
Change ID의 형식은 <number>,<patchset>임을 참고하세요.
Enqueue-ref
usage: zuul-admin enqueue-ref [-h] --tenant TENANT [--trigger TRIGGER]
--pipeline PIPELINE --project PROJECT --ref REF
[--oldrev OLDREV] [--newrev NEWREV]
Submit a trigger event
Directly enqueue a trigger event. This is usually used
to manually "replay" a trigger received from an external
source such as gerrit.
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--trigger TRIGGER trigger name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--ref REF ref name
--oldrev OLDREV old revision
--newrev NEWREV new revision
이 명령은 외부 소스에서 발생하는 트리거를 수동으로 시뮬레이션하기 위해 제공됩니다. 소스에서 다시 생성하기 어렵거나 불가능한 트리거를 테스트하거나 재생(replay)하는 데 유용합니다. enqueue-ref에 대한 인자는 소스와 트리거 유형에 따라 달라집니다. patchset-created 및 ref-updated와 같은 gerrit update hooks 에서 전달되는 인자에 대해 어느 정도 이해하고 있는 것이 좋습니다. 아래에 일반적인 작업에 대한 몇 가지 예제가 제공됩니다.
수동 큐 추가 예제 (Manual enqueue examples)
gerrit에서 오는 새로운 태그를 감지하고 일련의 코드 패키징 잡(job)을 수행하는 release 파이프라인을 갖는 것은 일반적입니다. 릴리스 잡에 예상치 못한 문제가 발생할 경우, 동일한 태그를 gerrit에서 다시 생성할 수 없으므로 사용자는 새 릴리스 태그를 지정하거나 잡의 수동 재트리거(re-triggering)를 요청해야 합니다. 잡을 다시 트리거하려면, 실패한 태그를 ref 인자로 전달하고 newrev를 프로젝트 저장소의 태그와 연관된 변경 사항(즉, git show X.Y.Z에서 확인되는 것)으로 설정하세요:
zuul-admin enqueue-ref --tenant openstack --trigger gerrit --pipeline release --project openstack/example_project --ref refs/tags/X.Y.Z --newrev abc123..
이 명령은 timer 드라이버에 의해 특정 시간에 실행되는 periodic 파이프라인의 잡을 비동기적으로 트리거하는 데에도 사용할 수 있습니다. 예를 들어, 다음 명령은 프로젝트의 현재 master 브랜치 최상단(top-of-tree)에 대해 periodic 잡을 트리거합니다:
zuul-admin enqueue-ref --tenant openstack --trigger timer --pipeline periodic --project openstack/example_project --ref refs/heads/master
또 다른 일반적인 파이프라인은 gerrit 병합 결과를 감지하는 post 큐입니다. 여기에서 트리거하는 것은 gerrit의 전체 ref-updated 이벤트를 다시 생성해야 하므로 조금 더 복잡합니다. master에 대한 새로운 커밋의 경우, Gerrit ref-updated 트리거는 “프로젝트의 refs/heads/master를 oldrev에서 newrev로 리셋”(여기서 newrev는 커밋된 변경 사항)하는 것을 의미합니다. 따라서 이벤트를 재생하려면, 프로젝트에서 git log를 확인하여 현재 HEAD와 이전 변경 사항을 가져온 다음 이벤트를 큐에 추가 할 수 있습니다:
NEW_REF=$(git rev-parse HEAD)
OLD_REF=$(git rev-parse HEAD~1)
zuul-admin enqueue-ref --tenant openstack --trigger gerrit --pipeline post --project openstack/example_project --ref refs/heads/master --newrev $NEW_REF --oldrev $OLD_REF
oldrev와 newrev의 값이 0인 경우 브랜치 생성 및 삭제를 의미할 수 있음을 참고하세요. 이러한 고급 작업에 대해서는 소스 코드를 참조하는 것이 가장 좋습니다.
Promote
usage: zuul-admin promote [-h] --tenant TENANT --pipeline PIPELINE --changes
CHANGES [CHANGES ...]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--changes CHANGES [CHANGES ...]
change ids
예제:
zuul-admin promote --tenant openstack --pipeline gate --changes 12345,1 13336,3
변경 사항 ID(change id)의 형식은 <number>,<patchset>임을 참고하세요.
Promote 액션은 파이프라인 내의 변경 사항 순서를 재정렬하여, 지정된 변경 사항을 큐(queue)의 최상단으로 이동시키는 데 사용됩니다.
Promote 액션의 가장 일반적인 사용 사례는 게이트(gate) 파이프라인에 이미 여러 패치가 대기 중인 상황에서 긴급 수정 사항(urgent fix)을 병합해야 할 때입니다. 특히 큐의 앞쪽에 있는 변경 사항들이 실패하여 수정 사항의 반영(land) 시간이 지연될 우려가 있거나, 현재 대기 중인 패치들 위에 수정 사항을 적용했을 때 검증을 통과하지 못할 우려가 있을 때 유용합니다.
종속(dependent) 파이프라인에 있는 항목(item)들의 경우, 자신보다 앞선 순서의 항목에 변경이 생기면 기존 잡들이 취소되고 새로운 순서에 따라 다시 시작됩니다.
독립(independent) 파이프라인에 있는 항목이 Promote 되는 경우에는 잡이 재시작되지 않습니다. 대신 파이프라인 내의 변경 사항 큐가 재정렬되어 해당 항목이 먼저 처리되며, 노드 요청 우선순위가 높아집니다.