OpenShift OKD实战：告别 kubeadmin，配置 HTPasswd 本地认证系统

原创已于 2025-12-30 16:34:17 修改 · 799 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#openshift #k8s #容器 #云计算 #云原生

于 2025-12-30 13:30:50 首次发布

2025博客之星年度评选已开启 10w+人浏览 3.6k人参与

OpenShift 实战：告别 kubeadmin，配置 HTPasswd 本地认证系统

摘要：OpenShift (OKD) 安装完成后默认提供的 kubeadmin 账号不仅密码难记，而且在 OAuth 重定向过程中常导致浏览器无法自动填充。本文将指导您通过 HTPasswd 身份提供程序 (Identity Provider)，创建自定义的管理员账号，实现更安全、便捷的集群访问控制。

1. 为什么我们需要自定义认证？

在刚安装好的 OpenShift/OKD 集群中，我们通常使用 kubeadmin 进行登录。但它存在明显的局限性：

临时性：设计初衷仅用于集群初始配置，官方建议配置正式认证后将其禁用。
体验差：密码是随机生成的长字符串，且登录 URL 包含动态参数（State），导致浏览器密码管理器经常失效。
审计困难：所有管理员共用一个账号，无法区分操作责任人。

通过配置 HTPasswd，我们可以创建类似 admin、dev-user 这样的本地账号，并赋予不同的权限。

2. 核心架构原理

OpenShift 的认证系统 (Authentication Operator) 支持多种身份提供程序 (IDP)，如 LDAP、GitHub、Google 等。

HTPasswd 是其中最简单的一种，它基于 Apache 的密码文件格式存储用户名和哈希加密后的密码。

流程图解：
用户登录 -> OpenShift OAuth Server -> 读取 Secret (htpasswd文件) -> 验证通过 -> 映射为 OpenShift User 对象

3. 实操步骤

环境说明：本文基于 OKD 4.15 SNO 环境，所有命令在 Control Plane 节点或已配置 oc 客户端的机器上执行。

步骤 1：生成密码文件 (CoreOS 容器化方式)

OKD 的底层操作系统通常为 Fedora CoreOS (FCOS)。这是一个不可变操作系统，默认不支持通过 yum 或 dnf 安装软件包。因此，我们不能直接安装 httpd-tools。

最标准的做法是使用 Podman 运行一个临时的容器来生成密码文件。

执行以下命令：

# 解释：
# podman run --rm: 运行一个临时容器，用完即删
# httpd:alpine: 使用轻量级的 Apache 镜像
# -B: 使用高强度的 Bcrypt 加密
# -c: 创建新文件
# /dev/stdout: 将结果输出到标准输出，然后通过重定向写入宿主机文件

# 创建用户 admin，密码为 MySecurePassword123! (请按需修改)
podman run --rm -ti --entrypoint htpasswd httpd:alpine -B -b -c /dev/stdout admin MySecurePassword123! > /tmp/users.htpasswd

注：如果您需要添加第二个用户，请参考第 4 章“进阶管理”中的追加方法。

步骤 2：创建 OpenShift Secret

将刚才生成的密码文件上传到 openshift-config 命名空间中。

oc create secret generic htpass-secret \
  --from-file=htpasswd=/tmp/users.htpasswd \
  -n openshift-config

步骤 4：配置 OAuth 资源

修改集群的 OAuth 配置，告诉它使用我们刚才创建的 Secret 作为身份源。

# 使用 patch 命令动态更新配置
oc patch oauth cluster --type merge -p '{"spec":{"identityProviders":[{"name":"local-users","mappingMethod":"claim","type":"HTPasswd","htpasswd":{"fileData":{"name":"htpass-secret"}}}]}}'

等待几分钟，Authentication Operator 会自动检测到配置变化，并重启 OAuth Server 的 Pod。

步骤 5：验证并授权

登录测试：
打开无痕浏览器，访问 OpenShift 控制台。您应该能看到登录界面多了一个 “local-users” 的选项。使用 admin 登录。
注意：此时登录进去后，您只是一个普通用户，看不到任何项目。
授予集群管理员权限 (Cluster Admin)：
切回终端（使用原本的 kubeadmin 身份），执行授权命令：

# 将 cluster-admin 角色绑定给用户 admin
oc adm policy add-cluster-role-to-user cluster-admin admin

再次刷新控制台：
现在 admin 用户应该拥有了完全的管理员视图。

4. 进阶管理：如何修改密码或添加新用户？

⚠️ 重要提示：OpenShift Web 控制台不支持直接管理 HTPasswd 用户。
您无法在界面上点击“添加用户”按钮来创建新账号。所有用户管理操作必须通过命令行更新 Secret 来完成。

场景：CoreOS 环境下追加新用户 (如 `test01`)

由于 SNO 节点运行在 CoreOS 上，我们继续使用 podman 来操作密码文件。

1. 在物理文件中追加用户

注意：这里不要使用 -c 参数（否则会覆盖旧文件）。

# 假设之前的密码文件还在 /tmp/users.htpasswd
# 我们将其挂载到容器中进行修改
ssh core@192.168.179.132 "podman run --rm -v /tmp/users.htpasswd:/auth/users.htpasswd --entrypoint htpasswd httpd:alpine -B -b /auth/users.htpasswd test01  newpassword123"

2. 更新集群 Secret

修改物理文件后，必须同步更新到 OpenShift 的 Secret 对象中，否则集群无法感知。

ssh core@192.168.179.132 "oc set data secret/htpass-secret --from-file=htpasswd=/tmp/users.htpasswd -n openshift-config"

3. 等待生效

执行更新后，OpenShift 的 OAuth Server 会在 1-2 分钟内自动重新加载 Secret，无需重启 Pod。之后您就可以用新用户 test01 登录了。

故障排查：如果原始密码文件丢失了怎么办？

由于 /tmp 目录在系统重启后会被清空，或者因为误操作导致 users.htpasswd 丢失，您可以选择以下三种方案进行恢复。

方案一：从集群 Secret 中“逆向”还原 (强烈推荐)

这是最稳妥的办法。我们可以将正在使用的 Secret 导出并解码，还原出当前的密码文件。

# 将 Secret 中的数据导出并 Base64 解码，写入到新文件中
oc get secret htpass-secret -n openshift-config -o jsonpath='{.data.htpasswd}' | base64 -d > /tmp/users.htpasswd

执行完此命令后，您就找回了最新的密码文件，可以继续进行追加或修改操作。

方案二：彻底重来 (暴力覆盖)

如果您不在意保留旧用户，或者想重置整个用户体系，可以直接生成一个新文件并覆盖 Secret。

参考本文“步骤 1”生成全新的密码文件。

执行强制覆盖更新：

oc create secret generic htpass-secret --from-file=htpasswd=/tmp/new_users.htpasswd -n openshift-config --dry-run=client -o yaml | oc apply -f -

方案三：架构师建议 (持久化存储)

为了避免文件丢失，建议一开始就不要将文件存放在 /tmp。

最佳实践：将文件存放在 /home/core/auth/ 目录下（需手动创建目录），并纳入配置管理（如 GitOps）的版本控制中。

5. 移除 kubeadmin (可选)

当您确信自定义管理员账号工作正常后，为了安全，可以移除默认的 kubeadmin。

oc delete secrets kubeadmin -n kube-system

警告：此操作不可逆，请务必确保新账号 admin 已拥有 cluster-admin 权限。

总结：
通过配置 HTPasswd，我们建立了一套独立、可控、易于记忆的本地账户体系。这对于中小规模的 OpenShift 集群或边缘计算节点 (SNO) 来说，是替代 kubeadmin 的最佳实践。