4. kube-apiserver 参数详解：认证、授权、准入控制、审计日志、etcd 连接等关键参数配置

kube-apiserver 是 Kubernetes 控制面的核心组件，所有对集群的读写操作（包括 kubectl、Pod 内部调用、调度器、控制器管理器）都必须经过它。理解其关键参数配置，是保障集群安全、稳定与可观测性的基础。本章按请求处理的生命周期顺序，逐一解析认证、授权、准入控制、审计日志及 etcd 连接的核心参数。

4.1 请求处理生命周期总览

一个 API 请求在 kube-apiserver 内部依次经过以下五个阶段，每个阶段都有对应的参数控制其行为：

  1. 认证（Authentication）：验证请求发起者的身份。
  2. 授权（Authorization）：判断该身份是否有权限执行请求的操作。
  3. 准入控制（Admission Control）：在对象持久化前，对请求内容进行修改或校验。
  4. 审计日志（Audit Logging）：记录请求的详细信息，用于事后追溯。
  5. etcd 持久化：将最终的对象数据存储到后端 etcd 集群。
核心原则： 认证失败则直接拒绝，不进入授权阶段；授权失败则不进入准入控制阶段。审计日志在请求处理的不同阶段都会记录事件。
kube-apiserver 请求处理生命周期 1. 认证 Authentication 2. 授权 Authorization 3. 准入控制 Admission Control 4. 审计日志 Audit Logging 5. etcd 持久化 关键说明： • 认证失败 → 直接返回 401 Unauthorized，不进入后续阶段。 • 授权失败 → 返回 403 Forbidden，不进入准入控制。 • 审计日志在请求进入、处理中、响应返回等多个阶段均会记录事件。

4.2 认证（Authentication）参数

kube-apiserver 支持多种认证方式，可以同时启用。请求到达时，会按顺序尝试每种认证模块，只要有一个成功即通过认证。

参数 默认值 说明
--client-ca-file 空 指定 CA 证书文件路径，用于验证客户端 TLS 证书。启用 TLS 双向认证（X.509 证书认证）。
--token-auth-file 空 指定静态令牌文件路径（CSV 格式：token,user,uid,group）。适用于服务账户或自动化工具。
--oidc-issuer-url 空 OIDC 提供者的 URL。启用 OpenID Connect 认证，常用于集成企业 SSO（如 Dex、Keycloak）。
--oidc-client-id 空 OIDC 客户端 ID，用于验证 ID Token 的 audience 字段。
--oidc-username-claim sub 指定 ID Token 中的哪个 claim 作为用户名。
--service-account-key-file 空 指定 PEM 编码的公钥文件，用于验证 ServiceAccount 签名的 JWT Token。可重复指定多个。
--authentication-token-webhook-config-file 空 指定 webhook 配置文件路径，用于将 TokenReview 请求发送到外部认证服务。
生产建议： 至少同时启用 --client-ca-file（X.509 证书）和 --service-account-key-file（ServiceAccount Token）。对于多集群或企业环境，强烈建议集成 OIDC 认证，避免使用静态令牌文件。

4.3 授权（Authorization）参数

授权模块决定一个已认证的用户能否执行特定操作。Kubernetes 支持多种授权模式，可以组合使用。

参数 默认值 说明
--authorization-mode AlwaysAllow 指定授权模式，逗号分隔。常用值：Node、RBAC、Webhook、ABAC、AlwaysDeny。生产环境推荐 Node,RBAC。
--authorization-webhook-config-file 空 指定 webhook 配置文件路径，用于将 SubjectAccessReview 请求发送到外部授权服务。
--authorization-webhook-cache-authorized-ttl 5m0s 授权通过结果的缓存时间。
--authorization-webhook-cache-unauthorized-ttl 30s 授权拒绝结果的缓存时间。
安全警告： 永远不要在非测试环境使用 --authorization-mode=AlwaysAllow。该模式会绕过所有权限检查，任何拥有 API Server 网络访问权限的客户端都可以执行任意操作。

4.4 准入控制（Admission Control）参数

准入控制器在对象被持久化到 etcd 之前拦截请求，可以修改请求内容（Mutating）或校验请求内容（Validating）。

参数 默认值 说明
--enable-admission-plugins 内置默认列表 启用额外的准入控制器插件，逗号分隔。例如：PodSecurity,NodeRestriction,NamespaceLifecycle。
--disable-admission-plugins 空 禁用默认启用的准入控制器插件。
--admission-control-config-file 空 指定准入控制器配置文件路径，用于精细化配置每个插件的参数（如 PodSecurity 的豁免命名空间）。
关键插件推荐：
  • NamespaceLifecycle：防止在正在删除的命名空间中创建新对象。
  • NodeRestriction：限制 kubelet 只能修改自身节点和 Pod 对象。
  • PodSecurity：替代废弃的 PodSecurityPolicy，按命名空间级别实施 Pod 安全标准。
  • MutatingAdmissionWebhook / ValidatingAdmissionWebhook：允许通过 Webhook 扩展自定义准入逻辑。

4.5 审计日志（Audit Logging）参数

审计日志记录每个 API 请求的详细信息，是安全审计和故障排查的关键数据源。

参数 默认值 说明
--audit-log-path 空 审计日志文件路径。如果为空，则不输出审计日志。
--audit-log-maxage 30 保留旧审计日志文件的最大天数。
--audit-log-maxbackup 10 保留的旧审计日志文件的最大数量。
--audit-log-maxsize 100 审计日志文件轮转前的最大大小（MB）。
--audit-policy-file 空 指定审计策略文件路径。策略文件定义了哪些请求、哪些资源、哪些操作需要记录，以及记录的详细级别（None、Metadata、Request、RequestResponse）。
--audit-webhook-config-file 空 指定 webhook 配置文件路径，用于将审计事件发送到外部日志系统（如 Elasticsearch、Splunk）。
审计策略最佳实践：
  • 对 metadata 级别的操作（如 get、list、watch）记录 Metadata 级别即可。
  • 对 create、update、delete 操作记录 RequestResponse 级别，以便追溯变更内容。
  • 对 ServiceAccount 的 Token 请求（TokenReview）建议记录 Request 级别。

4.6 etcd 连接参数

etcd 是 Kubernetes 集群的持久化后端，所有集群状态都存储在 etcd 中。连接参数直接影响集群的可用性和性能。

参数 默认值 说明
--etcd-servers 空 etcd 集群的地址列表，逗号分隔。例如：https://10.0.0.1:2379,https://10.0.0.2:2379。
--etcd-cafile 空 用于验证 etcd 服务端证书的 CA 证书文件路径。
--etcd-certfile 空 kube-apiserver 与 etcd 通信时使用的客户端证书文件路径。
--etcd-keyfile 空 客户端证书对应的私钥文件路径。
--etcd-prefix /registry etcd 中 Kubernetes 数据的键前缀。多集群共享同一 etcd 时，必须使用不同的前缀。
--etcd-compaction-interval 5m0s etcd 历史压缩的时间间隔。压缩会清理旧版本数据，释放存储空间。
关键安全配置： 生产环境必须启用 etcd 的 TLS 双向认证。确保 --etcd-cafile、--etcd-certfile、--etcd-keyfile 三个参数都正确配置。未加密的 etcd 通信意味着集群所有数据（包括 Secret）都在网络上明文传输。
kube-apiserver 与 etcd 集群连接架构 kube-apiserver --etcd-servers etcd 节点 1 etcd 节点 2 etcd 节点 3 连接参数说明： • --etcd-servers: 节点地址列表 • --etcd-cafile: 服务端 CA 证书 • --etcd-certfile: 客户端证书 • --etcd-keyfile: 客户端私钥 • --etcd-prefix: 数据键前缀 • --etcd-compaction-interval: 压缩间隔

4.7 综合配置示例

以下是一个生产环境 kube-apiserver 的启动参数示例，涵盖了上述所有关键配置：

kube-apiserver \
  --advertise-address=192.168.1.10 \
  --secure-port=6443 \
  --service-cluster-ip-range=10.96.0.0/12 \
  --service-node-port-range=30000-32767 \
  \
  # 认证配置
  --client-ca-file=/etc/kubernetes/pki/ca.crt \
  --service-account-key-file=/etc/kubernetes/pki/sa.pub \
  --oidc-issuer-url=https://dex.example.com \
  --oidc-client-id=kubernetes \
  --oidc-username-claim=email \
  \
  # 授权配置
  --authorization-mode=Node,RBAC \
  \
  # 准入控制配置
  --enable-admission-plugins=NodeRestriction,PodSecurity,NamespaceLifecycle \
  --admission-control-config-file=/etc/kubernetes/admission-config.yaml \
  \
  # 审计日志配置
  --audit-log-path=/var/log/kubernetes/audit.log \
  --audit-log-maxage=30 \
  --audit-log-maxbackup=10 \
  --audit-log-maxsize=100 \
  --audit-policy-file=/etc/kubernetes/audit-policy.yaml \
  \
  # etcd 连接配置
  --etcd-servers=https://10.0.0.1:2379,https://10.0.0.2:2379,https://10.0.0.3:2379 \
  --etcd-cafile=/etc/kubernetes/pki/etcd/ca.crt \
  --etcd-certfile=/etc/kubernetes/pki/etcd/server.crt \
  --etcd-keyfile=/etc/kubernetes/pki/etcd/server.key \
  --etcd-prefix=/registry
参数配置检查清单：
  • ✅ 认证：至少启用 X.509 证书认证 + ServiceAccount Token 认证。
  • ✅ 授权：使用 Node,RBAC 模式，禁用 AlwaysAllow。
  • ✅ 准入控制：启用 NodeRestriction、PodSecurity、NamespaceLifecycle。
  • ✅ 审计日志：配置日志文件路径和轮转策略，并编写审计策略文件。
  • ✅ etcd 连接：启用 TLS 双向认证，配置多节点地址列表。
← 上一章 📖 返回目录 下一章 →