如何用 k3s token create 创建带 TTL 的 agent 加入 token 并管理生命周期

如何用 k3s token create 创建带 TTL 的 agent 加入 token 并管理生命周期

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s

k3s 集群的默认 server token 泄露后很难安全更换：它同时是 cluster bootstrap 数据的加密口令，--agent-token变更后也需要协调重启所有 server。为了让节点加入使用一次性、可过期、可随时删除的 token，k3s 借鉴kubeadm token create实现了 bootstrap token secret，并提供k3s token子命令完成 create/list/delete 操作（设计背景见 agent-join-token ADR）。本文的任务是：在已运行的 k3s server 上创建一个带 TTL 的 agent 加入 token，用它把一台新 agent 接入集群，并验证 token 到期后自动清理、必要时手动删除。

适用前提：一台已通过安装脚本或手工方式启动的 k3s server（安装脚本会生成 kubeconfig 文件/etc/rancher/k3s/k3s.yaml并自动启动服务，见 README.md）。token 命令通过 kubeconfig 访问集群，需要在能读到该 kubeconfig 的 server 节点上执行，也可用--kubeconfig（或环境变量KUBECONFIG）显式指定。

创建带 TTL 的加入 token

在 server 上执行：

k3s token create --ttl=10m --description="agent join"

该命令在kube-system命名空间创建一个类型为bootstrap.kubernetes.io/token的 Secret，并把生成的 token 打印到标准输出，之后只打印这一次，需要自行保存。命令支持的位置参数和参数（定义见 pkg/cli/cmds/token.go）：

• 位置参数：可选地指定 token 值，格式为<id>.<secret>（测试用例中使用过10mint.ida18trbbk43szwk这类写法，见 token_test.go）。不指定时自动生成随机值；
• --ttl：到期后自动删除的时长，示例格式1s, 2m, 3h，默认值为 24 小时；设为0表示永不过期；
• --description：说明该 token 用途的文本，会显示在 list 输出中；
• --groups：使用该 token 认证时附加的额外用户组，不指定时默认加入system:bootstrappers:k3s:default-node-token（见 pkg/kubeadm/token.go）；
• --usages：描述 token 的允许用途，不指定时取 cluster-bootstrap 包定义的全部已知用途。

创建后可以先用 list 确认。text 模式输出列固定为TOKEN、TTL、EXPIRES、USAGES、DESCRIPTION、EXTRA GROUPS（列名与输出格式见 pkg/cli/token/token.go），TTL 列显示的是距过期的剩余时间，--ttl=0的 token 显示为<forever>：

k3s token list

上面--ttl=10m的 token 在列表中的样子（测试中的正则10mint\s+[0-9]m对应的示例形态，仅作文档示例，具体剩余时间随执行时刻变化）：

10mint 9m 2025-01-01T12:10:00Z signing,authentication agent join system:bootstrappers:k3s:default-node-token

需要结构化解析时用-o切换输出格式，只支持text、json、yaml三种：

k3s token list -o json

如果指定的 token id 已经存在，创建会直接失败，报错a token with id "<id>" already exists（见 token.go）。

用 token 将 agent 加入集群

bootstrap token 只能用于加入 agent，不能用于加入 server——这是 ADR 中明确的设计决定（agent-join-token.md）。

测试套件采用的方式是：在 agent 节点上把 token 写入 k3s 配置文件/etc/rancher/k3s/config.yaml，然后启动 k3s-agent 服务（见 token_test.go）：

echo 'token: 10mint.ida18trbbk43szwk' | tee -a /etc/rancher/k3s/config.yaml > /dev/null systemctl start k3s-agent

其中 token 值替换为你在 server 上创建时打印的完整 token（id.secret两段都要）。

另一种等价路径是使用安装脚本并传入 token 环境变量（README.md）：

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=<token> sh -

或手工运行 agent 进程（myserver:6443替换为你的 server 地址，NODE_TOKEN即创建时打印的 token）：

sudo k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}

注意区分两类 token：server 启动时生成、存放在/var/lib/rancher/k3s/server/node-token的是默认node-token；本文创建的 bootstrap token 是独立的短期凭证，两者都可用于 agent 加入，但只有后者带 TTL 且可单独删除。

验证 agent 已加入、token 在列

加入完成后在 server 上确认节点数与状态。k3s 安装脚本安装的工具链提供kubectl，k3s 自身也提供k3s kubectl（README.md）：

k3s kubectl get nodes

成功条件：新 agent 对应的 Node 出现在列表中且状态为 Ready，节点总数比加入前多 1。仓库的 docker 测试正是以「节点数量增加且全部 Ready」作为 agent 加入成功的判定（token_test.go）。

再执行k3s token list，确认该 token 的TTL列在递减、EXPIRES列是 RFC3339 格式的到期时间戳。

生命周期管理：自动过期与手动删除

自动清理。k3s 启用了tokencleaner控制器，TTL 到期后自动删除 bootstrap token secret（ADR 中的决定，见 agent-join-token.md）。仓库测试的做法是：创建一个--ttl=20s的 token 后，在 25 秒内轮询k3s token list，直到列表中不再包含该 token 的 id（token_test.go）。你可以用同样的方式核对自动清理是否生效：

k3s token create --ttl=20s 20sect.jxnpve6vg8dqm895 k3s token list # 到期后该 token 应从列表中消失

手动删除。未到期或永不过期的 token 可以用 delete 子命令删除，参数可以是完整 token 值或 token id（id 的校验模式见 pkg/kubeadm/token.go 引入的 cluster-bootstrap 工具）。删除成功时输出形如bootstrap token "deltok" deleted，之后k3s token list中不再包含该 id（对应测试见 token_test.go）：

k3s token delete deltok.0123456789abcdef

永久 token。--ttl=0创建的 token 永不自动过期，适合长期使用的 agent 加入凭证，list 中显示<forever>/<never>（测试见 token_test.go）；代价是它只能手动删除，失去 TTL 带来的收敛能力。

已加入节点不受 token 失效影响。token 过期或手动删除不会把已加入集群的 agent 踢出去：ADR 明确允许 agent 在加入 token 失效后仍凭 Node Authorization 维持连接，只有「token 无效且 Node 对象被删除」时 agent 才无法接入（agent-join-token.md）。

限制与不适用场景

• bootstrap token 不能用于加入 server 节点；server 加入用的--token是集群级默认 token，其更换路径是k3s token rotate -t <旧token> --new-token=<新token>，并要求重启所有节点（rotate 的定义见 pkg/cli/cmds/token.go，测试见 token_test.go）。
• token secret 只在 create 时打印一次；k3s token list只显示 id 等元信息，遗失的 token 只能删除后重建。
• list 的 text 输出不提供 secret 部分，需要完整 token 值时必须保留创建时的打印输出。

完整的 token 生命周期覆盖（创建、加入、到期清理、rotate）可以参考仓库中的两个 docker 测试：tests/docker/bootstraptoken/bootstraptoken_test.go 与 tests/docker/token/token_test.go。

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s