K8S配置中apiVersion详解

少妇的美梦
92 阅读3分钟

✅ 一、apiVersion 是什么？

在 Kubernetes 的 YAML 资源定义中，apiVersion 表示该资源所属的 API 组（API Group）和版本（Version） 。
Kubernetes 的 API 是分组、分版本演进的，目的是实现向后兼容和渐进式升级。

apiVersion: apps/v1        # API 组 / 版本
kind: Deployment

✅ 二、apiVersion 有哪几种类型？

Kubernetes 的 API 分为两类：

1. 核心 API 组（Core Group）

  • 没有组名，直接写版本号。
  • 包含最基础、最稳定的资源。
  • apiVersion 格式：v1

✅ 常见资源：

apiVersion: v1
kind: Pod
---
apiVersion: v1
kind: Service
---
apiVersion: v1
kind: ConfigMap
---
apiVersion: v1
kind: Secret
---
apiVersion: v1
kind: PersistentVolumeClaim

2. 命名 API 组（Named API Groups）

  • 有明确的组名，格式：<group>/<version>
  • 用于组织功能相关的资源（如工作负载、网络、批处理等）

✅ 常见 API 组及资源：

API Group（组名）常见资源示例 apiVersion
appsDeployment, StatefulSet, DaemonSet, ReplicaSetapps/v1
batchJob, CronJobbatch/v1
networking.k8s.ioIngress, NetworkPolicynetworking.k8s.io/v1
rbac.authorization.k8s.ioRole, ClusterRole, RoleBindingrbac.authorization.k8s.io/v1
storage.k8s.ioStorageClass, VolumeAttachmentstorage.k8s.io/v1
autoscalingHorizontalPodAutoscalerautoscaling/v2
apiextensions.k8s.ioCustomResourceDefinition (CRD)apiextensions.k8s.io/v1

📌 注意：同一个资源可能在多个版本中存在（如 extensions/v1beta1/Deployment 已废弃，现用 apps/v1）。

✅ 三、API 版本的生命周期（Alpha / Beta / Stable）

每个 API 版本都有状态，决定其稳定性：

状态后缀说明
Alphav1alpha1, v2alpha1实验性，可能变更或删除，默认不启用
Betav1beta1, v2beta1相对稳定，但可能有 breaking change，默认启用
Stablev1, v2（无后缀）稳定版，保证向后兼容，生产推荐使用

🔒 生产环境务必使用 stable（如 apps/v1）版本！

✅ 四、可以自定义 apiVersion 吗？

答案：可以，但不是直接“写一个新名字”，而是通过 CRD（CustomResourceDefinition）机制扩展 API。

1. 自定义资源（Custom Resource, CR）

  • 你可以定义自己的资源类型（如 Database, CronJobMonitor）。
  • 通过创建 CustomResourceDefinition（CRD）来注册新 API。

2. 自定义 apiVersion 的格式

当你创建 CRD 时，需要指定：

  • group（你的自定义组名，如 mycompany.com）
  • version（如 v1）
  • kind（资源类型名，如 MyApp）

最终的 apiVersion 就是：<group>/<version>

🔧 示例：创建一个自定义资源

步骤 1：定义 CRD

# myapp-crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myapps.mycompany.com  # 格式：<plural>.<group>
spec:
  group: mycompany.com        # ← 自定义 API 组
  versions:
    - name: v1
      served: true
      storage: true
      schema: ... # 省略校验规则
  scope: Namespaced
  names:
    plural: myapps
    singular: myapp
    kind: MyApp

步骤 2：使用自定义资源

# myapp-instance.yaml
apiVersion: mycompany.com/v1   # ← 这就是你“自定义”的 apiVersion！
kind: MyApp
metadata:
  name: example-app
spec:
  replicas: 3
  image: nginx:1.25

✅ 现在你就可以用 kubectl get myapps 管理它了！

✅ 五、如何查看集群支持的所有 apiVersion？

# 查看所有 API 资源及其 apiVersion
kubectl api-resources

# 查看某个资源的详细信息（包括支持的版本）
kubectl explain deployment

# 查看所有 API 组和版本
kubectl api-versions

输出示例：

apps/v1
batch/v1
networking.k8s.io/v1
v1
mycompany.com/v1   # ← 你自定义的也会出现在这里！

✅ 六、总结

问题答案
apiVersion 有几种类型？两类：核心组（v1） 和 命名组（group/version）
常见的有哪些？v1, apps/v1, batch/v1, networking.k8s.io/v1 等
可以自定义吗？✅ 可以！通过 CRD（CustomResourceDefinition） 创建自己的 group/version
自定义后怎么用？apiVersion: your-group.com/v1，配合自定义控制器（Operator）实现业务逻辑
生产环境建议？使用 Stable 版本（无 alpha/beta 后缀） ，避免废弃 API

通过 CRD 机制，Kubernetes 实现了强大的可扩展性，这也是 Operator 模式、Helm Chart、Prometheus Operator 等生态工具的基础。

avatar
文章
阅读
粉丝