k8s.gcr.io 官方Kubernetes组件镜像文档

1. 镜像概述和主要用途

概述

k8s.gcr.io 是 Kubernetes 官方镜像仓库，提供构建和运行 Kubernetes 集群所需的核心组件镜像。这些镜像由 Kubernetes 社区维护，包含控制平面组件（如 kube-apiserver、etcd、kube-controller-manager）和节点组件（如 kubelet、kube-proxy）等，是搭建 Kubernetes 集群的基础依赖。

主要用途

作为 Kubernetes 集群的核心运行载体，提供集群控制、节点管理、服务编排等关键功能的运行环境，确保集群各组件的版本一致性和兼容性。

2. 核心功能和特性

• 官方认证：镜像由 Kubernetes 官方构建并签名，确保安全性和可靠性，通过严格的兼容性测试。
• 版本强关联：镜像版本与 Kubernetes 集群版本严格对应（如 v1.28.0 镜像适配 Kubernetes v1.28.x 集群），避免版本冲突。
• 组件完整性：包含构建完整集群所需的全部核心组件，无需额外依赖第三方镜像。
• 轻量级设计：基于精简基础镜像（如 distroless）构建，减少资源占用，提升运行效率。
• 跨环境适配：兼容主流容器运行时（containerd、Docker）和 Linux 操作系统（Ubuntu、CentOS 等）。

3. 使用场景和适用范围

使用场景

• 自建 Kubernetes 集群的初始化部署（如通过 kubeadm、kubeasz 等工具）。
• 现有集群的组件升级或版本替换（如控制平面组件滚动更新）。
• 开发/测试环境中模拟 Kubernetes 集群运行。
• 生产环境构建高可用（HA）集群。

适用范围

• 适用于需要完全控制集群配置的场景（如企业数据中心、私有云、边缘环境）。
• 支持单节点测试集群到大规模生产集群（节点数从 1 到数千）。

4. 使用方法和配置说明

4.1 镜像拉取与标记

由于 k8s.gcr.io 仓库在部分网络环境下访问受限，通常需从第三方镜像仓库（如 docker.io）拉取镜像后重新标记，或直接从官方仓库拉取（需确保网络可达）。

方法 1：通过 Docker 拉取并标记

# 1. 从第三方镜像仓库拉取（以 docker.io 为例，假设镜像已同步）
docker pull docker.io/<第三方仓库名>/<组件名>:<版本>

# 2. 重新标记为 k8s.gcr.io 格式（匹配 Kubernetes 组件配置要求）
docker tag docker.io/<第三方仓库名>/<组件名>:<版本> k8s.gcr.io/<组件名>:<版本>

# 示例：拉取并标记 kube-apiserver v1.28.0
docker pull docker.io/mirrorgooglecontainers/kube-apiserver:v1.28.0
docker tag docker.io/mirrorgooglecontainers/kube-apiserver:v1.28.0 k8s.gcr.io/kube-apiserver:v1.28.0

方法 2：通过 containerd 的 ctr 命令拉取并标记

对于使用 containerd 作为运行时的环境，可直接通过 ctr 命令操作：

# 1. 在 k8s.io 命名空间下从第三方仓库拉取
ctr -n k8s.io image pull docker.io/<第三方仓库名>/<组件名>:<版本>

# 2. 重新标记为 k8s.gcr.io 格式
ctr -n k8s.io image tag docker.io/<第三方仓库名>/<组件名>:<版本> k8s.gcr.io/<组件名>:<版本>

# 示例：拉取并标记 kube-proxy v1.28.0
ctr -n k8s.io image pull docker.io/mirrorgooglecontainers/kube-proxy:v1.28.0
ctr -n k8s.io image tag docker.io/mirrorgooglecontainers/kube-proxy:v1.28.0 k8s.gcr.io/kube-proxy:v1.28.0

4.2 注意事项

• 网络访问：k8s.gcr.io 需通过 Google Cloud 网络访问，国内用户建议优先使用第三方镜像仓库（如 docker.io 的同步镜像）。
• 版本匹配：拉取镜像版本必须与目标集群版本一致（如部署 v1.28.0 集群需使用 v1.28.0 镜像）。
• 镜像清理：标记完成后可删除原第三方仓库镜像以节省存储空间（如 docker rmi docker.io/mirrorgooglecontainers/kube-apiserver:v1.28.0）。

5. 配置参数与环境变量

k8s.gcr.io 镜像的运行参数通常通过 Kubernetes 资源对象（Deployment、DaemonSet、Pod）配置，具体参数因组件而异。例如：

• kube-apiserver：通过 --advertise-address 指定访问地址、--etcd-servers 配置 etcd 连接地址等。
• kubelet：通过 --node-ip 设置节点 IP、--cgroup-driver 指定 cgroup 驱动等。

环境变量配置需参考对应组件官方文档，示例链接：

• kube-apiserver 配置说明
• kubelet 配置说明

6. 部署方案示例

6.1 集群初始化前的镜像准备（以 Kubernetes v1.28.0 为例）

# 控制平面组件拉取与标记
docker pull docker.io/mirrorgooglecontainers/kube-apiserver:v1.28.0
docker tag docker.io/mirrorgooglecontainers/kube-apiserver:v1.28.0 k8s.gcr.io/kube-apiserver:v1.28.0

docker pull docker.io/mirrorgooglecontainers/kube-controller-manager:v1.28.0
docker tag docker.io/mirrorgooglecontainers/kube-controller-manager:v1.28.0 k8s.gcr.io/kube-controller-manager:v1.28.0

# 节点组件拉取与标记（containerd 环境）
ctr -n k8s.io image pull docker.io/mirrorgooglecontainers/kube-proxy:v1.28.0
ctr -n k8s.io image tag docker.io/mirrorgooglecontainers/kube-proxy:v1.28.0 k8s.gcr.io/kube-proxy:v1.28.0

6.2 说明

k8s.gcr.io 镜像通常不通过 docker run 直接启动，而是由 Kubernetes 自身通过控制平面组件（如 kubelet）根据资源配置（如 PodSpec）自动调度运行。部署集群时，确保所有节点已完成镜像拉取和标记，即可通过 kubeadm init 等工具完成初始化。

7. 参考资料

• Kubernetes 官方镜像仓库
• kubeadm 镜像拉取说明
• Kubernetes 组件文档