kube-controller-manager 镜像文档

镜像概述

registry.k8s.io/kube-controller-manager 是 Kubernetes 控制平面的核心组件之一，负责运行一系列控制器进程，这些控制器通过持续监控集群状态并执行必要操作，确保集群的实际状态始终与用户定义的期望状态一致。该组件是维持 Kubernetes 集群稳定性和自愈能力的关键，直接参与集群资源的生命周期管理。

核心功能与特性

主要控制器类型

kube-controller-manager 集成了多种控制器，包括但不限于：

• 节点控制器（Node Controller）：监控节点健康状态，当节点故障时标记节点为不可用并触发相应处理。
• 副本控制器（Replication Controller）：确保指定数量的 Pod 副本持续运行，自动创建或删除 Pod 以维持期望副本数。
• 端点控制器（Endpoint Controller）：维护 Service 与 Pod 之间的端点映射关系（Endpoints）。
• 命名空间控制器（Namespace Controller）：处理命名空间的生命周期管理，包括命名空间删除时的资源清理。
• 服务账号控制器（ServiceAccount Controller）：管理服务账号（ServiceAccount）及其访问凭证。
• 资源配额控制器（ResourceQuota Controller）：确保命名空间内的资源使用不超过定义的配额限制。
• 部署控制器（Deployment Controller）：管理 Deployment 资源，实现 Pod 和 ReplicaSet 的声明式更新。

核心特性

• Leader 选举：多实例部署时通过 Leader 选举机制确保仅一个实例活跃，避免重复操作。
• 自愈能力：持续监控集群状态，自动修复偏离期望状态的资源（如 Pod 故障重建）。
• 可配置性：支持通过命令行参数或配置文件调整行为，如日志级别、API 超时时间等。

使用场景与适用范围

适用场景

• Kubernetes 集群部署：作为控制平面组件，必须部署在所有 Kubernetes 集群中（单节点集群或多节点集群）。
• 集群运维：用于维护集群资源的正常运行，适用于开发、测试、生产等各类环境的 Kubernetes 集群。

部署位置

通常部署在 Kubernetes 集群的控制平面节点（Master 节点），与 kube-apiserver、etcd、kube-scheduler 等控制平面组件协同工作。

使用方法与配置说明

运行方式

kube-controller-manager 通常作为系统服务（如 systemd）或容器化应用运行在控制平面节点，通过 kube-apiserver 与集群交互，依赖 etcd 存储集群状态数据。

关键配置参数

以下为常用命令行参数（完整参数可通过 kube-controller-manager --help 查看）：

• --master：指定 kube-apiserver 的地址（格式：http://<apiserver-ip>:<port>），已逐步被 --kubeconfig 替代。
• --kubeconfig：指定 kubeconfig 文件路径，用于与 kube-apiserver 建立安全连接。
• --leader-elect：启用 Leader 选举（多实例部署时必填，默认启用）。
• --controllers：指定要启用的控制器列表（默认启用所有控制器，格式：*,!controller-name 可排除特定控制器）。
• --logtostderr：将日志输出到标准错误（默认启用），可配合 --v 设置日志级别（如 --v=2）。
• --root-ca-file：指定根 CA 证书路径，用于验证 kube-apiserver 的证书。
• --service-account-private-key-file：服务账号私钥文件路径，用于签署服务账号令牌。

部署示例

简化版 Docker 运行命令（仅作演示，生产环境建议通过集群管理工具部署）

docker run -d \
  --name kube-controller-manager \
  --restart=always \
  -v /etc/kubernetes/pki:/etc/kubernetes/pki \
  -v /etc/kubernetes/kubeconfig:/etc/kubernetes/kubeconfig \
  registry.k8s.io/kube-controller-manager:v1.28.0 \
  --kubeconfig=/etc/kubernetes/kubeconfig \
  --leader-elect=true \
  --controllers=*,!bootstrapsigner,!tokencleaner \
  --logtostderr=true \
  --v=2

典型 systemd 服务配置示例（节选）

[Unit]
Description=Kubernetes Controller Manager
Documentation=[***]

[Service]
ExecStart=/usr/local/bin/kube-controller-manager \
  --kubeconfig=/etc/kubernetes/controller-manager.conf \
  --leader-elect=true \
  --controllers=*,!bootstrapsigner,!tokencleaner \
  --logtostderr=true \
  --v=2
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

注意事项

• 必须与 kube-apiserver、etcd 版本兼容（建议使用同一 Kubernetes 版本的镜像）。
• 生产环境中需启用 TLS 加密（通过 --kubeconfig 或证书参数配置），确保与 kube-apiserver 的通信安全。
• 多控制平面节点部署时，需确保所有实例的配置一致，并正确配置 Leader 选举参数（如 --leader-elect-lease-duration、--leader-elect-renew-deadline 等）。

镜像版本与兼容性

镜像标签遵循 Kubernetes 版本号格式（如 v1.28.0），需与集群中其他控制平面组件（kube-apiserver、kube-scheduler 等）版本保持一致，以确保兼容性。建议通过 Kubernetes 官方文档确认各版本间的兼容性要求。