概述

apiserverinternal API

介绍

apiserverinternal API 的核心功能是提供 API Server 的 内部状态管理和协调机制，主要服务于以下场景：

  1. 存储版本管理
    • 跟踪资源对象在 etcd 中的存储版本（Storage Version）
    • 确保多版本 API 的兼容性转换
  2. API Server 实例协调
    • 在多个 API Server 实例间同步状态信息
    • 支持高可用部署模式下的协调
  3. 内部状态监控
    • 暴露 API Server 的内部健康状态和性能指标

核心 API 资源类型

在 apiserverinternal.k8s.io/v1alpha1 中定义了以下关键资源：

  1. StorageVersion
  2. StorageVersionStatus
  3. ServerStorageVersion

关键工作流程

(1) 存储版本协商

  1. 当资源存在多版本（如 v1 和 v1beta1）时：
    • 所有 API Server 实例通过 StorageVersion 资源协商出一个统一的存储版本
    • 写入 etcd 时统一转换为该版本
  2. 客户端请求时按需转换回目标版本

(2) 状态同步示例

# 示例：Deployment 资源的存储版本状态
apiVersion: apiserverinternal.k8s.io/v1alpha1
kind: StorageVersion
metadata:
  name: deployments.apps
status:
  storageVersions:
  - apiServerID: "kube-apiserver-xyz"
    encodingVersion: "apps/v1"
    decodableVersions: ["apps/v1", "apps/v1beta1"]
  commonEncodingVersion: "apps/v1"

实际应用场景

(1) 版本升级监控

# 查看当前存储版本协商状态
kubectl get storageversions.apiserverinternal.k8s.io

(2) 多版本兼容性保障

  • 确保旧版本客户端（如使用 apps/v1beta1）仍能读写数据
  • API Server 自动处理版本转换

(3) API Server 运维

  • 检测集群中不同 API Server 实例的版本一致性
  • 灰度升级时监控版本迁移状态

源码学习路径

  1. 类型定义： staging/src/k8s.io/api/apiserverinternal/v1alpha1/types.go
  2. 控制器逻辑： pkg/controlplane/storageversiongc/ （存储版本垃圾回收） pkg/apiserver/storageversion/ （版本协调主逻辑）
  3. 客户端交互： staging/src/k8s.io/client-go/applyconfigurations/apiserverinternal/

调试技巧

# 查看所有资源的存储版本
kubectl get storageversions.apiserverinternal.k8s.io -o yaml

# 检查特定资源（如 Deployment）
kubectl get storageversions deployments.apps -o yaml

设计意义

  1. 解耦存储与 API 版本：允许 etcd 存储格式独立于对外暴露的 API 版本
  2. 平滑升级：支持多版本共存期间的无缝转换
  3. 分布式协调：解决多 API Server 实例的状态一致性问题