kube-apiserver 镜像文档

镜像概述和主要用途

本镜像为 k8s.gcr.io/kube-apiserver 仓库中选定标签的镜像，用于提供 Kubernetes API 服务。作为 Kubernetes 控制平面的核心组件，kube-apiserver 负责接收、验证、处理和响应所有来自集群内外部的 API 请求，是集群中各个组件（如 kubelet、kube-controller-manager、kube-scheduler、kubectl 等）通信的统一入口。

核心功能和特性

核心功能

API 请求处理：接收并处理 RESTful API 请求（如创建 Pod、Deployment 等资源），支持 JSON 和 Protobuf 格式。
认证与授权：通过插件机制（如 X.509 证书、Token、OAuth2 等）验证客户端身份，并基于 RBAC 等策略进行权限控制。
数据验证：对 API 请求中的资源配置进行语法和语义验证，确保资源定义符合 Kubernetes API 规范。
API 版本管理：支持多版本 API（如 v1、apps/v1 等），提供版本间兼容性和特性演进能力。
etcd 交互：作为唯一与 etcd（集群数据存储）直接交互的控制平面组件，负责资源数据的读写操作。
请求限流与熔断：通过 --rate-limit-exempt、--max-requests-inflight 等参数控制请求流量，防止过载。
TLS 加密：默认启用 TLS 加密所有 API 通信，确保传输安全。

使用场景和适用范围

典型场景

Kubernetes 集群部署：作为控制平面核心组件，用于构建单节点或多节点 Kubernetes 集群。
开发与测试环境：在本地或测试环境中模拟 Kubernetes 控制平面，验证 API 行为或资源配置。
离线/隔离环境部署：在无法直接访问 k8s.gcr.io 仓库的环境中（如内网、防火墙隔离环境），通过本镜像快速部署 kube-apiserver。
版本兼容性测试：通过指定不同标签（对应不同 Kubernetes 版本），测试资源定义或客户端工具与 API 服务的兼容性。

使用方法和配置说明

拉取镜像

通过 docker pull 命令拉取指定标签的镜像（标签通常对应 Kubernetes 版本，如 v1.28.0）：

bash
docker pull [镜像仓库地址]/kube-apiserver:[标签]
# 示例：拉取 v1.28.0 版本
docker pull my-registry/kube-apiserver:v1.28.0

注：实际使用时需替换 [镜像仓库地址] 为该镜像的具体仓库地址（如私有仓库或镜像服务地址）。

运行容器示例

kube-apiserver 依赖证书、配置文件及 etcd 存储，运行时需通过挂载卷（Volume）提供必要文件，并通过命令行参数配置核心功能。以下为简化示例（实际生产环境需结合集群配置调整）：

bash
docker run -d \
  --name kube-apiserver \
  --network host \  # 使用主机网络，确保与集群内其他组件通信
  -v /etc/kubernetes/pki:/etc/kubernetes/pki:ro \  # 挂载证书目录（只读）
  -v /etc/kubernetes/manifests:/etc/kubernetes/manifests:ro \  # 挂载静态 Pod 配置（可选）
  my-registry/kube-apiserver:v1.28.0 \
  kube-apiserver \
    --advertise-address=192.168.1.100 \  # 对外暴露的 IP 地址
    --etcd-servers=[***] \  # etcd 集群地址
    --kubelet-https=true \  # 启用与 kubelet 的 HTTPS 通信
    --tls-cert-file=/etc/kubernetes/pki/apiserver.crt \  # API 服务 TLS 证书
    --tls-private-key-file=/etc/kubernetes/pki/apiserver.key \  # API 服务 TLS 私钥
    --client-ca-file=/etc/kubernetes/pki/ca.crt \  # 客户端 CA 证书（用于验证客户端证书）
    --authorization-mode=RBAC \  # 授权模式（如 RBAC、Node 等）
    --enable-admission-plugins=NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,ResourceQuota \  # 启用的准入插件
    --max-requests-inflight=400 \  # 最大并发请求数（防止过载）
    --request-timeout=300s  # 请求超时时间

配置参数说明

kube-apiserver 主要通过命令行参数配置，以下为常用参数说明：

参数名	用途说明	示例值
`--advertise-address`	指定 API 服务对外暴露的 IP 地址，供集群内其他组件（如 kubelet）访问。	`192.168.1.100`
`--etcd-servers`	etcd 集群的访问地址（多个地址用逗号分隔）。	`[***]`
`--tls-cert-file`	API 服务对外提供的 TLS 证书文件路径（PEM 格式）。	`/etc/kubernetes/pki/apiserver.crt`
`--tls-private-key-file`	与 `--tls-cert-file` 对应的 TLS 私钥文件路径。	`/etc/kubernetes/pki/apiserver.key`
`--client-ca-file`	客户端 CA 证书文件路径，用于验证客户端（如 kubectl、kubelet）提交的证书。	`/etc/kubernetes/pki/ca.crt`
`--authorization-mode`	授权模式，常用 `RBAC`（基于角色的访问控制），可组合多个模式（如 `RBAC,Node`）。	`RBAC`
`--kubelet-https`	是否通过 HTTPS 与 kubelet 通信（默认 `true`）。	`true`
`--enable-admission-plugins`	启用的准入插件列表（顺序重要），控制资源创建/更新前的校验逻辑。	`NamespaceLifecycle,LimitRanger,ServiceAccount`
`--max-requests-inflight`	允许的最大并发未完成请求数，用于限流（默认 `400`）。	`400`
`--request-timeout`	API 请求超时时间（默认 `60s`），长耗时操作（如 `kubectl logs`）可适当延长。	`300s`

注意事项

标签与版本兼容性：镜像标签需与目标 Kubernetes 集群版本严格匹配（如 v1.28.0 对应 Kubernetes v1.28.0），避免版本不兼容导致集群异常。
依赖组件：kube-apiserver 需与 etcd、kube-controller-manager、kube-scheduler 等控制平面组件协同工作，单独运行仅用于测试，不构成完整集群。
证书与安全：必须正确挂载 TLS 证书、CA 证书等安全文件，否则 API 通信可能面临安全风险（如中间人***）。
生产环境部署：生产环境中建议通过 Kubernetes 静态 Pod、kubeadm 或集群管理工具（如 kops、OpenShift）部署，而非直接使用 docker run。
资源限制：根据集群规模调整资源配置（如 CPU、内存），避免因资源不足导致 API 服务响应缓慢或崩溃。