命令行参考

CLI 命令以非交互方式运行。除使用支持的 --dry-run 参数外，写操作会直接执行。参数必须放在子命令之后。运行 kticket <command> --help 或 kticket access <command> --help 可查看对应命令的选项。

长选项统一使用双横线，例如 --username alice 或 --username=alice。帮助和示例均采用此风格；为兼容已有用法，仍接受单横线长选项。

--kubeconfig 和 --lang 也可以放在子命令之前。子命令指定的 --kubeconfig 会覆盖根级参数值。--lang 的值只影响 TUI，CLI 命令会忽略它。

命令概览

批量签发和命名空间多选通过 TUI 提供。CLI 的 issue 每次处理一个账户和一项授权配置。

License 命令

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 的说明见 License 购买与激活。

选择集群与账户

CLI 账户命令支持 --kubeconfig 和 --context。默认读取 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

文件包含持有者令牌、API 服务器地址和已配置的 CA 数据。管理员 kubeconfig 通过文件引用的 CA 也会被读取并嵌入。未配置 CA 时，客户端使用系统信任根；禁用证书校验时，输出文件不包含 CA 数据。

集群名称取自所选管理员上下文。生成的上下文名称为 <account>@<cluster>，并被设为 current-context。上下文的默认命名空间为账户命名空间；访问其他命名空间的工作负载时，请使用 kubectl --namespace。--server 只修改地址，不改变集群名称。无法取得集群名称时，使用 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 文件。指定的账户必须存在且受 kticket 管理。

如果绑定清理失败，在重新创建同名账户前，请先阅读撤销与故障处理。

管理授权

所有 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

# 将 GRANT_ID 替换为列表中的授权 ID。
kticket access replace --username alice --grant-id GRANT_ID \
  --target-namespace app-staging --cluster-role view

# 重新查询列表，再使用当前授权 ID 执行移除。
kticket access list --username alice
kticket access remove --username alice --grant-id CURRENT_GRANT_ID

grant、replace 和 remove 支持 --dry-run，仅生成变更计划，不写入资源。未指定时立即执行。移除授权会保留账户及其凭据；外部授权不由 kticket 修改。

引用的角色和目标命名空间必须已存在，access 命令不会创建命名空间。同一命名空间中可以配置多项授权。权限变更对账户的所有有效凭据生效，但不会延长凭据有效期。

声明式授权配置

创建 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

检查通过 SubjectAccessReview 提交账户的 Kubernetes 身份及所属组。指定名称的资源可以不存在，因为此操作查询的是授权结果，并不请求该资源。结果为 ALLOWED、DENIED 或 UNAVAILABLE；只有 ALLOWED 对应成功退出状态。

授权列表仅展示已识别的 RBAC 绑定，并非完整的有效权限清单。即使移除了受管授权，外部授权仍可能允许该操作。