CLI 參考

CLI 指令不提供互動操作。除非設定支援的 --dry-run 旗標，否則寫入指令會立即執行。請將旗標放在子指令後。使用 kticket <command> --help 或 kticket access <command> --help 查看各指令的選項。

長選項使用兩個連字號，例如 --username alice 或 --username=alice。說明及範例統一採用此格式；為保持相容性，仍接受既有的單連字號長選項。

--kubeconfig 和 --lang 也可放在子命令之前。子命令指定的 --kubeconfig 會覆寫根層級的值。--lang 的值僅影響 TUI，CLI 命令會忽略它。

指令

TUI 支援批次簽發及多選命名空間。CLI issue 每次呼叫僅接受一個帳戶和一組授權選項。

授權指令

kticket license machine-id
kticket license install /path/to/kticket-license.ktlicense
kticket license status
kticket license inspect /path/to/kticket-license.ktlicense

購買、安裝路徑、--force 與 KTICKET_LICENSE_FILE 的說明請參閱授權購買與啟用。

叢集與帳戶選擇

CLI 帳戶指令接受 --kubeconfig 與 --context。kubeconfig 預設先使用 KUBECONFIG，再使用 ~/.kube/config；情境預設為該設定的目前情境。情境名稱必須已存在於 kubeconfig。

--namespace 選擇 ServiceAccount 所在的帳戶命名空間。對 issue、revoke 與 access 指令，預設為 kticket-users。對 list，省略命名空間表示所有命名空間。

帳戶命名空間與授予存取權的目標命名空間彼此獨立。指定目標時，issue 使用 --role-namespace，access 指令使用 --target-namespace。

簽發憑證

在 app-prod 中授予既有的 edit ClusterRole：

kticket issue --username bob --duration 8h \
  --access namespace --role edit --role-namespace app-prod \
  --output ./bob.kubeconfig

繫結既有的命名空間 Role：

kticket issue --username carol --access role \
  --role support --role-namespace app-prod

不新增授權，僅簽發憑證：

kticket issue --username alice --access none \
  --duration 1h --output ./alice-laptop.kubeconfig

--access none 保留既有權限。為既有帳戶重新簽發會替同一個 ServiceAccount 建立另一個權杖，不會取代先前的權杖。

收件者使用不同 API 端點時：

kticket issue --username eve --access namespace \
  --role view --role-namespace app-prod \
  --server https://api.example.com:6443

帳戶命名空間與 ServiceAccount 若不存在，將予以建立。角色與目標命名空間必須已存在。唯一例外是在此次簽發建立的帳戶命名空間中繫結既有的 ClusterRole。

簽發選項

省略存取旗標會授予叢集範圍的 cluster-admin 存取權。 需要較小範圍時，請明確指定旗標。issue 沒有 --dry-run 選項。

產生的 kubeconfig

檔案包含 Bearer 權杖、API 端點及已設定的 CA 資料，包括從管理員 kubeconfig 所參照檔案讀取的 CA 資料。未設定 CA 時，用戶端使用系統信任根憑證。不安全模式下，輸出不包含 CA 資料。

叢集名稱來自所選管理員情境。產生的情境為 <account>@<cluster>，並設為 current-context。其預設命名空間是帳戶命名空間；其他位置的工作負載請使用 kubectl --namespace。--server 只改變端點，不改變叢集名稱。若無法取得叢集名稱，kticket 使用 cluster。

預設檔名包含帳戶及叢集名稱，例如 alice.production-eu.kubeconfig。CLI --output 指定檔案；TUI 則要求既有目錄。

每份簽發的憑證都有獨立的 kubeconfig 使用者別名。簽發及到期時間請參閱憑證記錄。

列出帳戶與憑證

kticket list
kticket list --context my-cluster --namespace kticket-users
kticket list --credentials

帳戶清單包含受管理的角色繫結。--credentials 會加入已記錄的憑證 ID、時間戳記及稽核 ID。這些記錄描述由 kticket 簽發並記錄的憑證，並非所有可用權杖的完整清單。

撤銷帳戶

kticket revoke --context my-cluster --namespace kticket-users --username alice

撤銷會先刪除受管理的 ServiceAccount，再清理其受管理繫結。這會影響該帳戶 UID 的每個權杖，不會刪除命名空間或本機 kubeconfig 檔案。使用者名稱必須指向既有的受管理帳戶。

繫結清理失敗的帳戶，在重新建立前請參閱撤銷與失敗處理。

管理授權

所有 access 指令都需要 --username，並接受上述叢集與帳戶選擇旗標。可選的 --expected-uid 要求特定的 ServiceAccount UID，讓指令碼拒絕已刪除並重新建立的帳戶。

為既有帳戶新增授權，先預覽變更：

kticket access grant --username alice \
  --target-namespace app-staging --cluster-role edit --dry-run
kticket access grant --username alice \
  --target-namespace app-staging --cluster-role edit

命名空間 Role 使用 --role support。--cluster-role 與 --role 必須擇一。預設範圍為 namespace；叢集範圍的授權需要 --scope cluster --cluster-role NAME，且不指定目標命名空間。

列出授權，再用授權 ID 取代或移除：

kticket access list --username alice

# Replace GRANT_ID with an ID from the list.
kticket access replace --username alice --grant-id GRANT_ID \
  --target-namespace app-staging --cluster-role view

# List again, then use the current grant ID for removal.
kticket access list --username alice
kticket access remove --username alice --grant-id CURRENT_GRANT_ID

grant、replace 與 remove 支援 --dry-run，只計算計畫而不寫入資源。未指定時，變更立即套用。移除授權會保留帳戶及其憑證。外部指派不受 kticket 控制。

所有參照的角色及目標命名空間必須已存在。存取指令不會建立命名空間。同一命名空間可有多項授權。變更適用於帳戶的所有有效憑證，但不延長其到期時間。

宣告授權集合

建立 alice-access.yaml：

grants:
  - scope: namespace
    namespace: app-prod
    roleKind: ClusterRole
    roleName: view
  - scope: namespace
    namespace: app-staging
    roleKind: ClusterRole
    roleName: edit

預覽並套用：

kticket access plan --username alice --file alice-access.yaml
kticket access apply --username alice --file alice-access.yaml

此檔案描述該帳戶所需的完整kticket 管理的授權集合。未列出的受管理授權會被移除，外部指派則保留。grants: [] 移除全部受管理授權。grants 欄位必須明確指定陣列；不接受 null、重複授權或未知欄位。

命名空間 Role 使用 roleKind: Role。叢集範圍授權使用 scope: cluster 與 roleKind: ClusterRole，並省略 namespace。

apply 根據檔案及叢集目前狀態計算新計畫，不會執行先前儲存的計畫。取代時先移除舊繫結再建立新繫結，可能短暫中斷存取。部分失敗的行為請參閱權限變更。

檢查操作

檢查帳戶能否讀取 Pod 日誌：

kticket access check --username alice \
  --target-namespace app-staging --resource pods/log --verb get

檢查使用帳戶的 Kubernetes 身分與群組發出 SubjectAccessReview。指定的資源不必存在：這是授權查詢，不是資源請求。結果為 ALLOWED、DENIED 或 UNAVAILABLE；除非結果是 ALLOWED，否則 CLI 以非成功狀態結束。

授權清單顯示已知的 RBAC 指派，而非所有有效權限。移除受管理授權後，外部指派仍可能允許操作。