容器服务 TKE CAM Tool 工具介绍

tke-cam-tool 是一个基于 腾讯云 CAM (Cloud Access Management) 的 Kubernetes 认证工具。
通过生成 token，可以让 Kubernetes 集群支持基于 CAM 的认证，从而无需在本地存储集群静态密钥，如 token、X.509 证书等。
使用时，先生成一个可自动生成 token 的 kubeconfig ；执行 kubectl 命令时，使用该 kubeconfig 即可。
准备工作
使用前的准备工作如下：
1. 下载 TKE CAM Tool：根据您的客户端架构选择对应的二进制工具进行 下载。
2. 在集群内安装 tke-authenticator 组件，详情请参见 TKE Authenticator 组件实践指南。
3. 根据此工具的使用网络环境，开启集群 内网访问或外网访问。
使用说明
tke-cam-tool [COMMAND] [FLAGS...]
completion ：生成 bash 、 fish 、 powershell 或 zsh 的自动补全脚本。
exec-cred：生成 kubeconfig 或 token ，用于通过 Authentication Webhook 的身份认证机制，由部署在集群内的 tke-authenticator 组件来进行身份认证。
version ：打印当前工具的版本信息。
cache ：管理本地缓存，可清理所有默认本地缓存目录。
全局参数：
--log-config : zap logger 配置文件 的路径。如果没有指定，那么会默认打印 WARN 等级及以上的日志至 stderr ，并且使用格式 console。
--log-format : 覆盖配置文件或默认配置中的日志格式。可以是 console 或者 json。
-v , --log-level : 覆盖配置文集或默认配置中的日志等级。默认为 warn 。可选值： debug 、info 、warn、error、dpanic、panic、fatal。
exec-cred
生成 kubeconfig
生成一个用于访问集群的 kubeconfig 。
该 kubeconfig 利用 k8s.io/client-go 的 ExecCredential 凭据插件机制，将包含 token 的 ExecCredential 打印到 stdout ，再由 kubectl 解析使用。 token 的有效期为 4 分钟；过期后， kubectl 会重新生成 token。
tke-cam-tool exec-cred kubeconfig --cluster-id cls-xxx --region ap-guangzhou [FLAGS...]
必传参数：
--cluster-id : kubeconfig 需要操作的集群的 ID。这个是 TKE (Tencent Kubernetes Engine) 集群的唯一标识，可以从控制台获取。
--region : kubeconfig 需要操作的集群所在的地域。
获取集群信息密钥参数：
此处指定的密钥会被用于调用 DescribeClusterEndpoints 接口以获取集群 CA 证书以及 API
server 的地址。
--profile : profile 名称。指定从 tccli 的 profile 中获取腾讯云密钥。获取到的密钥包含腾讯云 Secret ID, Secret Key, 临时 Token。 profile 密钥文件的默认路径：Linux 和 macOS 为 ${HOME}/.tccli/PROFILE_NAME.credential （例如 /Users/bob/.tccli/myprofile.credential ）；Windows 为 %USERPROFILE%\\.tccli\\PROFILE_NAME.credential （例如 C:\\Users\\bob\\.tccli\\myprofile.credentials ）。
--secret-id : 指定腾讯云密钥 AK。
--secret-key : 指定腾讯云密钥 SK。当 --secret-id 被设置时， --secret-key 应当同时被设置。
--secret-token : 腾讯云密钥 Token。当 --secret-id 和 --secret-key 是腾讯云临时密钥时，必须设置本参数。
如果 --profile 和 --secret-id 都没有被设置，则会：
1. 先搜索环境变量 TENCENTCLOUD_CREDENTIALS_FILE 指定的密钥文件。如果该文件不存在，Linux 和 macOS 会搜索 ${HOME}/.tencentcloud/credentials （例如 /Users/bob/.tencentcloud/credentials ）；Windows 会搜索 %USERPROFILE%\\.tencentcloud\\credentials （例如 C:\\Users\\bob\\.tencentcloud\\credentials ）。
密钥文件格式为:
[default]
secret_id = xxxxx
secret_key = xxxxx
注意：
使用此密钥文件配置密钥时，不支持配置腾讯云密钥 Token 。
2. 若以上文件不存在，则会从环境变量 TENCENTCLOUD_SECRET_ID 中读取 secret ID， TENCENTCLOUD_SECRET_KEY 中读取 secret key， TENCENTCLOUD_TOKEN 中读取 token。
可选参数：
--api-version : 设置 kubeconfig 生成的 ExecCredential 的 API 版本， 可以是 v1 或 v1beta1 。如果设置为 v1 ，API version 会被设置为 client.authentication.k8s.io/v1 。如果设置为 v1beta1 ，API version 会被设置为 client.authentication.k8s.io/v1beta1 。默认是 v1beta1 。
-e , --external-id : 调用 AssumeRole 时所使用的 External ID 。只有当 --role 被设置时才生效。
--intranet : 生成一个用于在 VPC 内网访问集群的 kubeconfig ，默认为外网访问集群的 kubeconfig 。
-m , --merge : 将生成的 kubeconfig 与已有的 kubeconfig 进行合并。如果 --output 未指向现有的 kubeconfig 文件，则直接生成新文件。如果 --output 指向现有文件，则将访问集群所需的 cluster 、 user 和 context 信息添加到该文件，并将 current-context 设为新增的 context ；如果存在冲突，则报错。如果未设置 --merge ，但 --output 指向现有的 kubeconfig 文件，也会报错。
-o , --output : 指定 kubeconfig 的输出路径。如果没有被设置，打印生成的 kubeconfig 至 stdout 。
-r , --role : CAM 角色的 ARN 。如果这个参数被设置，则调用 AssumeRole 扮演此角色，并使用接口返回的临时密钥对 token 进行签名，此 token 的身份会是此 CAM 角色。格式为: qcs::cam::uin/ROOT_ACCOUNT_ID:role/ROLE_ID。
-s , --session-name : 调用 AssumeRole 时所使用的 SessionName  。只有当 --role 被设置时才生效。如果没有被设置，则使用默认值 tke-cam-tool-${timestamp} 。
--sts-endpoint : 调用 AssumeRole 接口时所使用的 STS(Security Token Service) 服务地址。只有当 --role 被设置时才生效。默认为 sts.tencentcloudapi.com 。
--tke-endpoint : 调用 DescribeClusterEndpoints 接口时所使用的 TKE(Tencent Kubernetes Engine) 服务地址。这个接口被用于获取生成 kubeconfig 所需要的 CA 证书以及 API server 的地址。
--token-cache-dir : 指定 token 的缓存路径。如果没有设置，则使用默认路径。
--token-no-cache : 禁用缓存的 token ，每次都生成新的 token 。
--token-profile : profile 名称。为生成的 kubeconfig 中指定从哪一个 tccli 的 profile 中获取腾讯云密钥。获取到的密钥包含腾讯云 Secret ID, Secret Key /临时 Token。这个参数会直接作为生成的 kubeconfig 中的 --profile command args。已设置 --role 时，该密钥用于调用腾讯云 API AssumeRole，获取用于签名 token 的临时密钥。未设置 --role 时，该密钥直接用于签名 token 。
注意：
使用 --token-profile 时，如果 profile 为 SSO 临时密钥，必须指定 --role 。也可不使用 --token-profile ，而是使用 SSO 临时密钥调用 GetFederationToken 或 AssumeRole 获取新的临时密钥；执行 kubectl 时，通过 TENCENTCLOUD_SECRET_ID 、 TENCENTCLOUD_SECRET_KEY 和 TENCENTCLOUD_TOKEN 环境变量指定该密钥。
--token-sts-host : 生成的 token 的 Host 头部中所包含的 STS 服务的地址， tke-authenticator 在校验 token 身份时， token 会被发送到此地址以确认身份。默认为 sts.internal.tencentcloudapi.com 。
说明：
当这个参数被设置时，请确保这个地址已经被添加到 tke-authenticator 的配置文件的 STSServiceEndpointsAllowed 中，或者添加到其 --sts-endpoint 参数中。
生成的 kubeconfig 示例：
apiVersion: v1
clusters:
  - cluster:
      certificate-authority-data: BASE64_PEM_ENCODED_CA_CERTIFICATE
      server: API_SERVER_ADDRESS
    name: cls-aaa
contexts:
  - context:
      cluster: cls-aaa
      user: cls-aaa-exec-cred-plugin
    name: cls-aaa-exec-cred-plugin-context
current-context: cls-aaa-exec-cred-plugin-context
kind: Config
preferences: {}
users:
  - name: cls-aaa-exec-cred-plugin
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - exec-cred
          - token
          - --cluster-id
          - cls-aaa
          - --role
          - qcs::cam::uin/ROOT_ACCOUNT_ID:role/ROLE_ID
          - --sts-endpoint
          - sts.internal.tencentcloudapi.com
          - --token-sts-host
          - sts.tencentcloudapi.com
        command: tke-cam-tool
        env: null
        interactiveMode: Never
        provideClusterInfo: false
生成访问 Kubernetes API Server 的 token
生成一个可以用于访问 Kubernetes API server 的 token。
这个 token 会由腾讯云 Secret ID 和 Secret Key 签名，通过 Authentication Webhook 的身份认证机制，由部署在集群内的 tke-authenticator 组件来进行身份认证。签名所使用的腾讯云密钥决定了最终 token 的身份， tke-authenticator 会使用这个 token 内的信息调用 STS(Security Token Service) 服务的 GetCallerIdentity 接口， 这个接口所返回的 ARN 即为 token 的腾讯云身份唯一标识。
生成的 token 被包装在 ExecCredential 的结构体中，以允许 kubectl 解析使用。
说明：
token 的有效期为 5 分钟。 ExecCredential 有效期为 4 分钟。从而给 token 留出 1 分钟时间到达 API server，并在到达时保持有效。
tke-cam-tool exec-cred token --cluster-id cls-xxx [FLAGS...]
必传参数：
--cluster-id : token 用于访问的集群 ID。这个是 TKE (Tencent Kubernetes Engine) 集群的唯一标识，可以从控制台获取。
签名密钥参数：
--secret-id : 指定腾讯云密钥 AK。
--secret-key : 指定腾讯云密钥 SK。当 --secret-id 被设置时， --secret-key 应当同时被设置。
--secret-token : 腾讯云密钥 Token。当 --role 没有被设置时，在生成访问 Kubernetes API server 的 token 时，这个腾讯云密钥 Token 会被直接加入到生成的 token 中。 当 --secret-id 和 --secret-key 是腾讯云临时密钥时，必须设置本参数。
--profile : profile 名称。指定从 tccli 的 profile 中获取腾讯云密钥。获取到的密钥包含腾讯云 AKSK/临时 Token。 profile 密钥文件的默认路径：Linux 和 macOS 为 ${HOME}/.tccli/PROFILE_NAME.credential （例如 /Users/bob/.tccli/myprofile.credentials ）；Windows 为 %USERPROFILE%\\.tccli\\PROFILE_NAME.credential （例如 C:\\Users\\bob\\.tccli\\myprofile.credentials ）。
注意：
注意使用 --profile 时，若 profile 为 tccli auth login 所生成的 SSO 临时密钥，则必须指定 --role 。或者不使用 --profile ，改为通过使用 SSO 临时密钥调用 GetFederationToken 或 AssumeRole 获得新的临时密钥，并通过环境变量 TENCENTCLOUD_SECRET_ID ， TENCENTCLOUD_SECRET_KEY ， TENCENTCLOUD_TOKEN 指定使用获取到的临时密钥。
当 --role 没有被设置时，此处指定的密钥会被用于直接对 token 进行签名。
当 --role 被设置时，会被用于调用腾讯云 API AssumeRole 从而获取用于对 token 进行签名的临时密钥。
如果 --profile 和 --secret-id 都没有被设置，则会：
1. 先搜索环境变量 TENCENTCLOUD_CREDENTIALS_FILE 指定的密钥文件。如果该文件不存在，Linux 和 macOS 会搜索 ${HOME}/.tencentcloud/credentials （例如 /Users/bob/.tencentcloud/credentials ）；Windows 会搜索 %USERPROFILE%\\.tencentcloud\\credentials （例如 C:\\Users\\bob\\.tencentcloud\\credentials ）。
密钥文件格式为：
[default]
secret_id = xxxxx
secret_key = xxxxx
注意：
使用此密钥文件配置密钥时，不支持配置腾讯云密钥 Token 。
2. 若以上文件不存在，则会从环境变量 TENCENTCLOUD_SECRET_ID 中读取 secret ID， TENCENTCLOUD_SECRET_KEY 中读取 secret key， TENCENTCLOUD_TOKEN 中读取 token。
其他可选参数：
--cache-dir : 设置 token 的缓存路径。如果没有设置，默认为 ${HOME}/.kube/cache/tke-cam-tool。
-e , --external-id : 调用 AssumeRole 时所使用的 External ID 。只有当 --role 被设置时才生效。
--no-cache : 禁用 token 缓存，每次都会生成新的 token 。
--region : 指定调用 AssumeRole 时所使用的 STS(Security Token Service) 服务所在地域。默认为 ap-guangzhou。请选择一个离运行此命令的机器最近的地域。
-r , --role : CAM 角色的 ARN 。如果这个参数被设置，则调用 AssumeRole 扮演此角色，并使用接口返回的临时密钥对 token 进行签名，此 token 的身份会是此 CAM 角色。格式为: qcs::cam::uin/ROOT_ACCOUNT_ID:role/ROLE_ID 。
-s , --session-name : 调用 AssumeRole 时所使用的 SessionName 。只有当 --role 被设置时才生效。如果没有被设置，则使用默认值 tke-cam-tool-${timestamp} 。
--sts-endpoint : 调用 AssumeRole 接口时所使用的 STS(Security Token Service) 服务地址。只有当 --role 被设置时才生效。默认为 sts.tencentcloudapi.com 。
--token-only : 只打印 ExecCredential 中所包含的 token 到 stdout 而非完整的 ExecCredential 。
--token-sts-host : 生成的 token 的 Host 头部中所包含的 STS 服务的地址， tke-authenticator 在校验 token 身份时， token 会被发送到此地址以确认身份。默认为 sts.internal.tencentcloudapi.com 。
说明：
当这个参数被设置时，请确保这个地址已经被添加到 tke-authenticator 的配置文件的 STSServiceEndpointsAllowed 中，或者添加到其 --sts-endpoint 参数中。
打印出来的包含 token 的 ExecCredential 示例：
{
  "kind": "ExecCredential",
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "spec": {
    "interactive": false
  },
  "status": {
    "expirationTimestamp": "2024-09-13T03:54:44Z",
    "token": "k8s-tke-v1.################"
  }
}
验证 token
通过调用 STS 服务的 GetCallerIdentity 接口，检查 token 是否有效。
打印 token 的 CAM 身份。如果 token 有效，则打印此身份信息。否则打印错误信息。token 的身份由签名所使用的腾讯云密钥决定。此命令可以在 token 无法被 tke-authenticator 认证时进行调试。您可以查看 token 的 CAM 身份，并确认其 ARN 是否与集群中的 CAMIdentityMapping 匹配。
tke-cam-tool exec-cred verify --cluster-id cls-xxx --token k8s-tke-v1.################ [FLAGS...]
必传参数：
--cluster-id : token 用于认证的集群的 ID。
-t , --token : 需要验证的 token 。
可选参数：
--sts-endpoint : 覆盖允许的 STS 服务地址列表。 GetCallerIdentity 请求仅被允许发送至这些地址以验证 token 的身份。 token 需要包含其中一个地址作为其 Host 头部。默认仅允许 sts.tencentcloudapi.com 和 sts.internal.tencentcloudapi.com。
--sts-region : 最近的 STS 服务地域。如果 token 中没有指定 X-TC-Region 头部，或者指定了但未签名，则使用此地域覆盖 token 中的 X-TC-Region 头部，以便使用最接近的 STS 服务来处理 GetCallerIdentity 请求。默认为 ap-guangzhou。
输出示例：
{
  "PrincipalType": "User",
  "ARN": "qcs::cam:101*****:uin/100*****",
  "CanonicalARN": "qcs::cam::uin/101*****:uin/100*****",
  "AccountID": "101*****",
  "UserID": "100*****",
  "SessionName": "",
  "SecretID": "AKID*****"
}
﻿
TKE CAM Tool 工具介绍

本页目录：

准备工作

使用说明

exec-cred

生成 kubeconfig

生成访问 Kubernetes API Server 的 token

验证 token
