Kubernetes学习笔记 – apiserverinternal

Source: 概述

Wed, 14 May 2025 00:00:00 +0000

介绍

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

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

核心 API 资源类型

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

StorageVersion
StorageVersionStatus
ServerStorageVersion

关键工作流程

(1) 存储版本协商

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

(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 实例的版本一致性
灰度升级时监控版本迁移状态

源码学习路径

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

调试技巧

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

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

设计意义

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

Source: types.go

Wed, 14 May 2025 00:00:00 +0000

StorageVersion

// Storage version of a specific resource.
type StorageVersion struct {
	metav1.TypeMeta `json:",inline"`
	// The name is <group>.<resource>.
	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

	// Spec is an empty spec. It is here to comply with Kubernetes API style.
	Spec StorageVersionSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`

	// API server instances report the version they can decode and the version they
	// encode objects to when persisting objects in the backend.
	Status StorageVersionStatus `json:"status" protobuf:"bytes,3,opt,name=status"`
}

StorageVersionList

// A list of StorageVersions.
type StorageVersionList struct {
	metav1.TypeMeta `json:",inline"`
	// Standard list metadata.
	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
	// +optional
	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
	// Items holds a list of StorageVersion
	Items []StorageVersion `json:"items" protobuf:"bytes,2,rep,name=items"`
}

Source: register.go

Wed, 14 May 2025 00:00:00 +0000

注册类型 APIGroupDiscoveryList 和 APIGroupDiscovery：

func addKnownTypes(scheme *runtime.Scheme) error {
	scheme.AddKnownTypes(SchemeGroupVersion,
		&StorageVersion{},
		&StorageVersionList{},
	)
	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
	return nil
}