CLI リファレンス

CLI コマンドは非対話型です。対応する --dry-run フラグを指定しない限り、書き込みコマンドは即時実行されます。フラグはサブコマンドの後に指定してください。各コマンドのオプションは kticket <command> --help または kticket access <command> --help で確認できます。

長いオプション名には --username alice や --username=alice のようにハイフンを 2 つ付けます。ヘルプと例ではこの形式に統一しています。互換性のため、従来のハイフン 1 つの形式も使用できます。

--kubeconfig と --lang はサブコマンドの前にも指定できます。サブコマンド側の --kubeconfig はルート側の値を上書きします。--lang の値は TUI にのみ適用され、CLI コマンドでは無視されます。

コマンド

TUI は一括発行と名前空間の複数選択に対応しています。CLI の issue は 1 回の呼び出しにつき 1 アカウントと 1 つの権限選択を受け付けます。

ライセンスコマンド

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 はエンドポイントのみ変更し、クラスター名は変更しません。クラスター名が取得できなければ 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 ID とグループで SubjectAccessReview を使用します。指定したリソースは存在しなくても構いません。これはリソース要求ではなく認可クエリです。結果は ALLOWED、DENIED、UNAVAILABLE のいずれかで、ALLOWED 以外では CLI が失敗ステータスで終了します。

権限一覧は既知の RBAC 割り当てを示し、すべての実効権限を示すものではありません。管理対象の権限を削除しても、外部の割り当てで操作が許可される場合があります。