API Version 对照

YAML 里的 apiVersion 由「组名/版本」两段组成，例如 apps/v1。核心组（core group）没有组名，直接写 v1。本篇按组分类列出常用资源的 apiVersion，并给出废弃版本对照和查询命令，写清单时随手可查。

核心资源

核心组资源 apiVersion 统一写 v1，不随资源种类变化：

资源	kind	apiVersion	命名空间作用域
Pod	Pod	v1	是
Service	Service	v1	是
ConfigMap	ConfigMap	v1	是
Secret	Secret	v1	是
Namespace	Namespace	v1	否（集群级）
PersistentVolume	PersistentVolume	v1	否（集群级）
PersistentVolumeClaim	PersistentVolumeClaim	v1	是
ServiceAccount	ServiceAccount	v1	是

扩展资源

除核心组外，其余资源都带组名，写 apiVersion 时组名和版本都要写全。

工作负载（apps/v1）

资源	kind	apiVersion
Deployment	Deployment	apps/v1
StatefulSet	StatefulSet	apps/v1
DaemonSet	DaemonSet	apps/v1
ReplicaSet	ReplicaSet	apps/v1

批处理（batch/v1）

资源	kind	apiVersion
Job	Job	batch/v1
CronJob	CronJob	batch/v1

网络（networking.k8s.io/v1）

资源	kind	apiVersion
Ingress	Ingress	networking.k8s.io/v1
IngressClass	IngressClass	networking.k8s.io/v1
NetworkPolicy	NetworkPolicy	networking.k8s.io/v1

权限（rbac.authorization.k8s.io/v1）

资源	kind	apiVersion	命名空间作用域
Role	Role	rbac.authorization.k8s.io/v1	是
RoleBinding	RoleBinding	rbac.authorization.k8s.io/v1	是
ClusterRole	ClusterRole	rbac.authorization.k8s.io/v1	否（集群级）
ClusterRoleBinding	ClusterRoleBinding	rbac.authorization.k8s.io/v1	否（集群级）

存储（storage.k8s.io/v1）

资源	kind	apiVersion
StorageClass	StorageClass	storage.k8s.io/v1
CSIDriver	CSIDriver	storage.k8s.io/v1

弹性伸缩（autoscaling）

资源	kind	apiVersion	说明
HorizontalPodAutoscaler	HorizontalPodAutoscaler	autoscaling/v2	推荐，支持多指标和自定义指标
HorizontalPodAutoscaler	HorizontalPodAutoscaler	autoscaling/v1	仅支持 CPU 利用率，老清单常见

策略与调度

资源	kind	apiVersion	所属组
PodDisruptionBudget	PodDisruptionBudget	policy/v1	policy
PriorityClass	PriorityClass	scheduling.k8s.io/v1	scheduling
RuntimeClass	RuntimeClass	node.k8s.io/v1	node

自定义资源（apiextensions.k8s.io/v1）

资源	kind	apiVersion
CustomResourceDefinition	CustomResourceDefinition	apiextensions.k8s.io/v1

CRD 定义出的自定义资源，其 apiVersion 由 CRD 的 spec.group 和 spec.versions 决定，形如 example.com/v1，不属于任何内置组。

废弃版本对照

Kubernetes 遵循「废弃公告 → 标记废弃 → 最终移除」的流程，旧清单升级集群前要先迁移 apiVersion。关键节点如下：

废弃版本	替代版本	影响资源	GA 版本	移除版本
extensions/v1beta1、apps/v1beta1、apps/v1beta2	apps/v1	Deployment、DaemonSet、ReplicaSet、StatefulSet	1.9	1.16
networking.k8s.io/v1beta1	networking.k8s.io/v1	Ingress、IngressClass	1.19	1.22
apiextensions.k8s.io/v1beta1	apiextensions.k8s.io/v1	CustomResourceDefinition	1.16	1.22
rbac.authorization.k8s.io/v1beta1	rbac.authorization.k8s.io/v1	Role、ClusterRole 等	1.8	1.22
batch/v1beta1	batch/v1	CronJob	1.21	1.25
policy/v1beta1	policy/v1	PodDisruptionBudget	1.21	1.25
autoscaling/v2beta2	autoscaling/v2	HorizontalPodAutoscaler	1.23	1.26
policy/v1beta1（PodSecurityPolicy）	无，改用 Pod Security Admission	PodSecurityPolicy	废弃于 1.21	1.25

迁移注意：

• apps/v1 的 Deployment 必须显式声明 spec.selector，且不可再修改；旧版本默认从模板标签推导，直接替换 apiVersion 会因缺少字段报错。
• Ingress 从 networking.k8s.io/v1beta1 升到 v1 后，后端写法由 serviceName/servicePort 改为 service.name/service.port，pathType 变为必填。
• PodSecurityPolicy（PSP）在 1.25 被整体移除，没有对应的 apiVersion 替代，集群安全基线改用内置的 Pod Security Admission（命名空间标签控制）。

快速检查清单里的废弃版本

用 kubectl get <kind> -o yaml 导出的清单中，apiVersion 字段反映的是写入时的版本。也可以用 kubectl api-resources --api-group=<组名> 确认当前集群实际支持的版本，升级集群前先跑一遍排查。

查询命令

命令	作用	示例
kubectl api-resources	列出集群支持的全部资源类型、组、简写和作用域	kubectl api-resources --namespaced=false
kubectl api-versions	列出集群支持的全部 apiVersion	kubectl api-versions | sort
kubectl explain	查看资源字段的说明文档，支持逐级深入	kubectl explain deployment.spec.template

kubectl explain 后跟「资源名.字段路径」，例如 kubectl explain pod.spec.containers.resources，可以查到字段类型和含义，不用翻官方文档。

API 成熟度

版本号后缀（alpha/beta/无后缀）代表该 API 的成熟度等级，越靠后越稳定：

等级	命名示例	默认启用	兼容性承诺	适用场景
Alpha	v1alpha1	否（需显式开启特性门控）	无，任何版本都可能改动或移除	尝鲜、内部测试
Beta	v1beta1	通常是	尽力兼容，但字段仍可能调整	非关键业务谨慎使用
Stable（GA）	v1、apps/v1	是	向后兼容，长期维护	生产环境

生产清单一律用 Stable 版本；遇到第三方组件只提供 Beta API 时，留意其废弃公告和集群升级窗口。

组名和版本别写错

apiVersion 校验严格区分大小写和分隔符：apps/v1 正确，Apps/V1、apps-v1 都会报 no kind ... is registered 或无法识别。写错时 kubectl apply 会直接失败，不会静默降级。