这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

apiserverinternal

提供 API Server 的 内部状态管理和协调机制

1 - 概述

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 实例的状态一致性问题

2 - types.go

apiserverinternal API 类型

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"`
}

3 - register.go

apiserverinternal API 类型注册

注册类型 APIGroupDiscoveryList 和 APIGroupDiscovery：

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