k3s token

K3s 使用令牌来保护节点加入过程。令牌用于验证集群对加入节点的认证，以及节点对集群的认证。

令牌格式

K3s 令牌可以以安全格式或简短格式指定。安全格式是首选，因为它允许客户端在发送凭据之前验证它要加入的集群的身份。

安全

安全令牌格式（有时被称为“完整”令牌）包含以下部分

<前缀><集群 CA 哈希>::<凭据>

• 前缀：一个固定为 K10 的前缀，用于识别令牌格式
• 集群 CA 哈希：集群服务器 CA 证书的哈希值，用于验证服务器对加入节点的认证。
  • 对于自签名 CA 证书，这是存储在磁盘上的 PEM 格式证书的 SHA256 校验和。
  • 对于自定义 CA 证书，这是根证书 DER 编码的 SHA256 校验和；通常称为证书指纹。
• 凭据：用于验证加入节点对集群的认证的用户名和密码，或承载令牌。

TLS 启动

当指定安全令牌时，加入节点执行以下步骤以验证它已连接到的服务器的身份，然后传输凭据

1. 在禁用 TLS 验证的情况下，从它要加入的服务器上的 /cacerts 下载 CA 捆绑包。
2. 计算 CA 证书的 SHA256 哈希值，如上所述。
3. 将计算出的 SHA256 哈希值与令牌中的哈希值进行比较。
4. 如果哈希值匹配，则验证服务器提供的证书是否可以通过服务器的 CA 捆绑包进行验证。
5. 如果服务器证书有效，则使用基本或承载令牌身份验证（取决于令牌类型）向集群提交凭据以加入集群。

简短

简短令牌格式仅包含用于验证加入节点对集群的认证的密码或承载令牌。

如果使用简短令牌，加入节点会隐式信任服务器提供的 CA 捆绑包；TLS 启动过程中的步骤 2-4 被跳过。初始连接可能容易受到中间人攻击。

令牌类型

K3s 支持三种类型的令牌。默认情况下，只有服务器令牌可用；其他令牌类型必须由管理员配置或创建。

类型	CLI 选项	环境变量
服务器	--token	K3S_TOKEN
代理	--agent-token	K3S_AGENT_TOKEN
引导	n/a	n/a

服务器

如果在启动集群中的第一个服务器时没有提供令牌，则会创建一个具有随机密码的令牌。服务器令牌始终以安全格式写入 /var/lib/rancher/k3s/server/token。

服务器令牌可用于将服务器节点和代理节点加入集群。创建集群后，服务器令牌无法更改，并且任何拥有服务器令牌的人实际上都拥有对集群的完全管理员权限。此令牌应妥善保管。

服务器令牌还用作用于加密持久存储到数据存储库中的机密信息的密钥的PBKDF2 密码短语，例如机密加密配置、WireGuard 密钥以及集群 CA 证书和服务帐户令牌的私钥。因此，令牌必须与集群数据存储库本身一起备份。

警告

除非使用自定义 CA 证书，否则在启动集群中的第一个服务器时，只能使用简短（仅密码）令牌格式。这是因为在服务器生成自签名集群 CA 证书之前无法获知集群 CA 哈希值。

有关使用自定义 CA 证书的更多信息，请参阅k3s certificate 文档。
有关备份集群的更多信息，请参阅备份和还原文档。

代理

默认情况下，代理令牌与服务器令牌相同。通过更改集群中所有服务器上的 CLI 选项或环境变量，可以在集群启动之前或之后设置代理令牌。代理令牌类似于服务器令牌，因为它是静态配置的，并且不会过期。

代理令牌以安全格式写入 /var/lib/rancher/k3s/server/agent-token。如果没有指定代理令牌，此文件将是一个指向服务器令牌的链接。

引导

版本门

从 2023 年 2 月的版本开始（v1.26.2+k3s1、v1.25.7+k3s1、v1.24.11+k3s1、v1.23.17+k3s1），支持 k3s token 命令，并且可以使用引导令牌加入节点。

K3s 支持动态生成的、自动过期的代理引导令牌。引导令牌只能用于加入代理。

k3s token

K3s 引导令牌使用与 kubeadm token 引导令牌相同的生成和验证代码，并且 k3s token CLI 类似。

NAME:
   k3s token - Manage bootstrap tokens

USAGE:
   k3s token command [command options] [arguments...]

COMMANDS:
   create    Create bootstrap tokens on the server
   delete    Delete bootstrap tokens on the server
   generate  Generate and print a bootstrap token, but do not create it on the server
   list      List bootstrap tokens on the server
   rotate    Rotate original server token with a new bootstrap token

OPTIONS:
   --help, -h  show help

k3s token create [token]

创建一个新令牌。[token] 是要写入的实际令牌，由 k3s token generate 生成。如果没有给出令牌，将生成一个随机令牌。

一个包含集群 CA 哈希值的以安全格式显示的令牌将被写入标准输出。应保存此命令的输出，因为令牌的秘密部分将无法再次显示。

标志	描述
--data-dir 值	用于保存状态的文件夹（默认值：/var/lib/rancher/k3s 或者 如果不是 root，则为 ${HOME}/.rancher/k3s）
--kubeconfig 值	要连接的服务器 [$KUBECONFIG]
--description 值	此令牌使用方式的人类友好描述
--groups 值	此令牌在用于身份验证时将作为其进行身份验证的额外组。（默认值：默认值："system:bootstrappers:k3s:default-node-token")
--ttl 值	令牌自动删除之前的持续时间（例如 1s、2m、3h）。如果设置为“0”，令牌将永远不会过期（默认值：24h0m0s）
--usages 值	描述可以使用此令牌的方式。（默认值："signing,authentication"）

k3s token delete

删除一个或多个令牌。可以提供完整令牌，也可以仅提供令牌 ID。

标志	描述
--data-dir 值	用于保存状态的文件夹（默认值：/var/lib/rancher/k3s 或者 如果不是 root，则为 ${HOME}/.rancher/k3s）
--kubeconfig 值	要连接的服务器 [$KUBECONFIG]

k3s token generate

生成一个随机生成的引导令牌。

不必使用此命令来生成令牌。只要令牌格式为 [a-z0-9]{6}.[a-z0-9]{16}，就可以自行生成，其中第一部分是令牌 ID，第二部分是秘密部分。

标志	描述
--data-dir 值	用于保存状态的文件夹（默认值：/var/lib/rancher/k3s 或者 如果不是 root，则为 ${HOME}/.rancher/k3s）
--kubeconfig 值	要连接的服务器 [$KUBECONFIG]

k3s token list

列出引导令牌，显示其 ID、描述和剩余的生存时间。

标志	描述
--data-dir 值	用于保存状态的文件夹（默认值：/var/lib/rancher/k3s 或者 如果不是 root，则为 ${HOME}/.rancher/k3s）
--kubeconfig 值	要连接的服务器 [$KUBECONFIG]
--output 值	输出格式。有效选项：text、json（默认值："text"）

k3s token rotate

版本门

从 2023 年 10 月的版本开始可用（v1.28.2+k3s1、v1.27.7+k3s1、v1.26.10+k3s1、v1.25.15+k3s1）。

使用新的引导令牌替换原始服务器令牌。运行此命令后，所有最初使用旧令牌加入的服务器和任何代理都必须使用新令牌重新启动。

如果未指定新令牌，则会为您生成一个令牌。

标志	描述
--data-dir 值	用于保存状态的文件夹（默认值：/var/lib/rancher/k3s 或者 如果不是 root，则为 ${HOME}/.rancher/k3s）
--kubeconfig 值	要连接的服务器 [$KUBECONFIG]
--server 值	要连接的服务器（默认值："https://127.0.0.1:6443"）[$K3S_URL]
--token 值	用于将服务器或代理加入集群的现有令牌 [$K3S_TOKEN]
--new-token 值	替换现有令牌的新令牌