企业官网建设流程全解析

kubeasz 客户端 kubeconfig 管理实战：用 ezctl kcfg-adm 签发限权限、限时限的用户证书

【免费下载链接】kubeasz使用Ansible脚本安装K8S集群，介绍组件交互原理，方便直接，不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeasz

kubeasz 集群安装完成后默认生成的 kubectl kubeconfig 拥有集群全部管理权限且有效期长达 50 年，直接分发给普通用户存在极大安全风险。本篇技术指南围绕 docs/op/kcfg-adm.md 展开，系统讲解 kubeasz 内置的ezctl kcfg-adm子命令如何基于 cfssl 证书签发与 Kubernetes RBAC 权限绑定，批量创建、列举和删除"限定权限、限定期限"的自定义用户 kubeconfig。读完本文，你将掌握-A / -D / -L / -e / -t / -u六个参数的完整用法，并理解从证书签名请求到 ClusterRoleBinding 落地的整条实现链路，可直接用于日常集群的多用户权限治理。

背景：为什么需要单独管理客户端 kubeconfig

Kubernetes 的 API Server 认证体系支持多种策略，kubeasz 默认采用客户端证书（client certificate）认证 + RBAC 授权的组合：用户持有由集群 CA 签发的客户端证书访问 API Server，证书中的CN（Common Name）字段被识别为用户名，随后由 RBAC 的 ClusterRoleBinding / RoleBinding 决定该用户能执行哪些操作。

kubeasz 安装完成后，deploy角色会通过 create-kubectl-kubeconfig.yml 生成一个供管理员使用的kubectl.kubeconfig，它绑定cluster-admin集群角色，证书期限长达 50 年。这份"万能钥匙"一旦泄露，攻击者即可完全控制集群，因此：

• 它不应该被直接分发给普通用户；
• 更合理的做法是像 kcfg-adm 这样，为每个使用者单独签发一份"限定权限（admin 或 view）、限定有效期"的证书和 kubeconfig。

原文档开头即强调："默认 k8s集群安装成功后生成客户端kubeconfig，它拥有集群管理的所有权限（不要将这个admin权限、50年期限的kubeconfig流露出去）"。ezctl kcfg-adm正是 kubeasz 封装好的解决方案，其思路可以概括为三句话：

1. 用 cfssl 以kcfgprofile 为用户签发带过期时间的客户端证书（CN 即用户名）；
2. 用 kubectl config 系列命令组装出独立的 kubeconfig 文件；
3. 用ClusterRoleBinding把该用户绑定到cluster-admin（admin）或view（只读）集群角色。

kcfg-adm 命令总览与参数说明

在/etc/kubeasz目录（kubeasz 安装根目录）下执行：

ezctl kcfg-adm <cluster> <args>

运行ezctl help kcfg-adm可以看到完整帮助信息：

Usage: ezctl kcfg-adm <cluster> <args> available <args>: -A to add a client kubeconfig with a newly created user -D to delete a client kubeconfig with the existed user -L to list all of the users -e to set expiry of the user certs in hours (ex. 24h, 8h, 240h) -t to set a user-type (admin or view) -u to set a user-name prefix examples: ./ezctl kcfg-adm test-k8s -L ./ezctl kcfg-adm default -A -e 240h -t admin -u jack ./ezctl kcfg-adm default -D -u jim-202101162141

各参数含义如下表：

上述默认值与参数校验规则均可在 ezctl 的函数实现中找到依据：脚本中初始化EXPIRY="4800h"、USER_TYPE="admin"、USER_NAME="user"，并分别用正则校验参数格式：

• -e必须匹配^[1-9][0-9]*h$，否则报错'-e' must be set like '2h, 5h, 50000h, ...'；
• -t只能是admin或view，否则报错'-t' can only be set as 'admin' or 'view'。

核心能力概括为两点：

• 可以设置过期时间：证书到期后 API Server 将拒绝该客户端证书，无需人工回收；
• 可以设置权限：admin对应clusterrole:cluster-admin（全权），view对应clusterrole:view（只读）。

使用实战：完整的五个操作步骤

以下以集群k8s-01为例（下文命令输出均为真实运行效果，时间戳来自原文档），演示从查看、新增、复核到删除的完整流程。

1. 查看集群当前自定义 kubeconfig

ezctl kcfg-adm k8s-01 -L 2021-01-24 16:32:43 INFO list-kcfg k8s-01 2021-01-24 16:32:43 INFO list-kcfg in cluster:k8s-01 USER TYPE EXPIRY(+8h if in Asia/Shanghai) --------------------------------------------------------------------------------- 2021-01-24 16:32:43 INFO list-kcfg k8s-01 success

初始情况下列表为空，表格只有表头。注意表头第三列的提示：证书过期时间按 UTC 存储，若当前时区为 Asia/Shanghai（东八区），实际到期时刻需 +8 小时。

2. 新增用户 user01：期限 24h、只读权限

ezctl kcfg-adm k8s-01 -A -u user01 -e 24h -t view 2021-01-24 17:32:33 INFO add-kcfg k8s-01 2021-01-24 17:32:33 INFO add-kcfg in cluster:k8s-01 with user:user01-202101241732 PLAY [localhost] ***************************************************************************************************** ...（此处省略输出） TASK [deploy : debug] ************************************************************************************************ ok: [localhost] => { "msg": "查看user01-202101241732自定义kubeconfig：/etc/kubeasz/clusters/k8s-01/ssl/users/user01-202101241732.kubeconfig" } PLAY RECAP *********************************************************************************************************** localhost : ok=12 changed=10 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 2021-01-24 17:32:41 INFO add-kcfg k8s-01 success

注意日志中的关键信息：传入的用户名user01被自动追加了时间戳，实际用户名为user01-202101241732（年月日时分），生成的 kubeconfig 位于：

/etc/kubeasz/clusters/k8s-01/ssl/users/user01-202101241732.kubeconfig

时间戳后缀的意义在于避免重名、便于审计：每次新增都会生成全新用户，历史证书即使泄露也可精准定位并按名删除。

3. 再增加用户 user02：期限 240h、admin 权限

ezctl kcfg-adm k8s-01 -A -u user02 -e 240h -t admin 2021-01-24 18:38:47 INFO add-kcfg k8s-01 2021-01-24 18:38:47 INFO add-kcfg in cluster:k8s-01 with user:user02-202101241838 PLAY [localhost] ***************************************************************************************************** ...（此处省略输出） TASK [deploy : debug] ************************************************************************************************ ok: [localhost] => { "msg": "查看user02-202101241838自定义kubeconfig：/etc/kubeasz/clusters/k8s-01/ssl/users/user02-202101241838.kubeconfig" } PLAY RECAP *********************************************************************************************************** localhost : ok=12 changed=9 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 2021-01-24 18:38:55 INFO add-kcfg k8s-01 success

本次只改了用户类型（admin）与有效期（240h），其余流程一致。admin 类型的分发对象应当是集群运维/管理员角色，务必谨慎。

4. 再次查看，确认两类用户已生效

ezctl kcfg-adm k8s-01 -L 2021-01-24 18:40:30 INFO list-kcfg k8s-01 2021-01-24 18:40:30 INFO list-kcfg in cluster:k8s-01 USER TYPE EXPIRY(+8h if in Asia/Shanghai) --------------------------------------------------------------------------------- user02-202101241838 cluster-admin 2021-02-03T10:34:00Z user01-202101241732 view 2021-01-25T09:28:00Z 2021-01-24 18:40:31 INFO list-kcfg k8s-01 success

列表按权限类型分组展示：user02-202101241838为cluster-admin（到期2021-02-03T10:34:00Z），user01-202101241732为view（到期2021-01-25T09:28:00Z），与创建时指定的-e、-t完全对应。过期时间换算到北京时间：user01 实际在2021-01-25 17:28失效，user02 实际在2021-02-03 18:34失效。

5. 删除用户 user01-202101241732 的权限

ezctl kcfg-adm k8s-01 -D -u user01-202101241732 2021-01-24 21:41:50 INFO del-kcfg k8s-01 2021-01-24 21:41:50 INFO del-kcfg in cluster:k8s-01 with user:user01-202101241732 clusterrolebinding.rbac.authorization.k8s.io "crb-user01-202101241732" deleted 2021-01-24 21:41:50 INFO del-kcfg k8s-01 success

删除操作删除的是名为crb-user01-202101241732的 ClusterRoleBinding。再次列出确认：

ezctl kcfg-adm k8s-01 -L 2021-01-24 21:42:02 INFO list-kcfg k8s-01 2021-01-24 21:42:02 INFO list-kcfg in cluster:k8s-01 USER TYPE EXPIRY(+8h if in Asia/Shanghai) --------------------------------------------------------------------------------- user02-202101241838 cluster-admin 2021-02-03T10:34:00Z 2021-01-24 21:42:02 INFO list-kcfg k8s-01 success

user01 已从列表消失，集群中只剩 user02 一个自定义用户。

底层实现解析：一条 kubeconfig 是如何诞生的

理解实现细节有助于在排障或二次开发时快速定位问题。整个功能由三部分协作完成：ezctl 脚本（命令入口）、deploy 角色的 Ansible 任务（证书与 kubeconfig 生成）、模板文件（证书请求与 RBAC 声明）。

ezctl 中的三个核心函数

在 ezctl 中，kcfg-adm函数负责参数解析与分发，随后分别调用：

• add-kcfg（新增）：执行USER_NAME="$USER_NAME"-$(date +'%Y%m%d%H%M')追加时间戳，然后调用 ansible-playbook：

  ansible-playbook -i "clusters/$1/hosts" -e "@clusters/$1/config.yml" \ -e "CUSTOM_EXPIRY=$EXPIRY" -e "USER_TYPE=$USER_TYPE" \ -e "USER_NAME=$USER_NAME" -e "ADD_KCFG=true" \ -t add-kcfg "roles/deploy/deploy.yml"

  注意它同时注入了四个关键变量：CUSTOM_EXPIRY（证书期限）、USER_TYPE（权限类型）、USER_NAME（最终用户名）、ADD_KCFG=true（开关），并只执行add-kcfgtag；

• del-kcfg（删除）：先通过 kubectl 的 jsonpath 过滤出 subjects 中匹配该用户名的 ClusterRoleBinding 名称，再kubectl delete clusterrolebindings删除绑定，最后清理clusters/$1/ssl/users/$USER_NAME*相关文件；
• list-kcfg（列举）：分别用 jsonpath 按roleRef.name == "cluster-admin"和roleRef.name == "view"过滤出两类用户，再用cfssl-certinfo读取各用户证书的not_after字段解析出过期时间，最后按"admin → view → 其他（unknown）"的顺序打印表格。

deploy 角色的证书签发链路

命令最终落到 deploy.yml（- hosts: localhost，角色为 deploy）。在 main.yml 中，只有当ADD_KCFG|bool为真时才导入 add-custom-kubectl-kubeconfig.yml（tag 为add-kcfg），整个任务流共 11 个步骤，可分为四段：

1. 准备目录与 CSR：创建ssl/users/目录，准备 CA 配置文件 ca-config.json.j2，并根据 user-csr.json.j2 模板生成用户证书签名请求。CSR 中"CN": "{{ USER_NAME }}"是关键——它将被 API Server 识别为 RBAC 中的用户名；
2. 签发证书：使用 cfssl 以kcfgprofile 签发客户端证书：

   cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json \ -profile=kcfg {{ USER_NAME }}-csr.json | cfssljson -bare {{ USER_NAME }}

   其中 ca-config.json.j2 中定义了kcfgprofile：usages 仅含signing、key encipherment、client auth（纯客户端用途），而expiry取值为{{ CUSTOM_EXPIRY }}——这正是-e参数能控制证书有效期的根本原因；

3. 组装 kubeconfig：依次执行kubectl config set-cluster（写入 API Server 地址与 CA 证书）、set-credentials（写入客户端证书与私钥）、set-context和use-context（--embed-certs=true将证书内容内嵌进文件，方便直接拷贝给用户使用）；
4. 绑定 RBAC 权限：根据 crb.yaml.j2 模板生成 ClusterRoleBinding 并通过kubectl apply -f生效。模板通过 Jinja2 条件判断决定绑定哪个集群角色：

   {% if USER_TYPE == 'admin' %} name: cluster-admin {% else %} name: view {% endif %}

   subjects 中kind: User、name: {{ USER_NAME }}，与证书 CN 严格对应，形成"证书认证 → 用户名 → RBAC 授权"的完整闭环。

产物目录结构

每次新增操作会在集群目录下留下以下文件（以 user01 为例）：

/etc/kubeasz/clusters/k8s-01/ssl/users/ ├── user01-202101241732-csr.json # 证书签名请求 ├── user01-202101241732.pem # 客户端证书 ├── user01-202101241732-key.pem # 客户端私钥 ├── user01-202101241732.kubeconfig # 最终交付给用户的配置文件 └── crb-user01-202101241732.yaml # ClusterRoleBinding 声明

其中crb-*.yaml是本次部署的编排产物，可留作审计；交付给用户时只需拷贝*.kubeconfig一份文件（证书已内嵌）。

使用建议与安全注意事项

综合原文档与实现源码，归纳以下几点实操建议：

1. 管理员 kubeconfig 严格保密：默认kubectl.kubeconfig是 50 年期限的 cluster-admin，只应保存在可信管理端，切勿随意外发；
2. 按需设置有效期：临时授权建议用短期限（如-e 24h），长期合作再放宽（如-e 240h）。证书到期自动失效，无需手动回收，是成本最低的"自动吊销"手段；
3. 只读权限优先：绝大多数查看类需求用-t view即可满足，admin仅授予确有管理职责的人员；
4. 删除需用完整用户名：-D参数要求传入带时间戳后缀的完整用户名（如user01-202101241732），因为删除逻辑是按完整名称匹配 ClusterRoleBinding 的 subjects；
5. 注意时区换算：-L输出的 EXPIRY 为 UTC 时间，东八区用户请自行 +8 小时判断实际失效时刻；
6. 强制校验保证安全：ezctl 对-e、-t的输入做了正则校验，错误格式会直接报错退出，避免误传非法参数导致意外行为。

如果需要对已有集群的 CA 或证书进行整体轮换，可参考 force_ch_certs.md；kcfg-adm 与 kubeasz 其他运维子命令（如 add-node、add-master、backup 等）的完整清单见 op-index.md，ezctl 的整体用法可查阅 ezctl.md。本文涉及的源码文件均可直接在仓库中继续深入阅读：ezctl、add-custom-kubectl-kubeconfig.yml、user-csr.json.j2、crb.yaml.j2、ca-config.json.j2。

【免费下载链接】kubeasz使用Ansible脚本安装K8S集群，介绍组件交互原理，方便直接，不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeasz