WHY

这篇文档面向 kubernetes 开发者，用于加深对 kubernetes API 结构的理解，理解 API 的多版本和代码生成的运作机制，也为 kubernetes CustomResourceDefinitions 设计提供规范和建议

本文主要有三部分内容

  1. CRD struct 设计中的规范和意见
  2. Kubernetes 中的 multiple version 模型
  3. Kubernetes 中的 code generation

其中第一部分的内容可以类比于任何编程语言的规范，编程规范为语言编程提供的统一的代码风格，提高代码的可读性，规范性和统一性，而本规范规定了在设计 kubernetes API struct 时的惯例约定，在团队内部形成相同的 API 风格，减少 API 设计之间的差异，增强可读性。

名词定义和规范

名称 说明
Kind 一个单数的首字母大写名称，用来表示某个特定的 Object，比如 Cat，Dog，Deployment，Pod 等
GroupVersion 每个 API 必须归属于某个 group/version 下，比如 deployment 归属于 "apps/v1"，以便于 api 的迭代升级管理
Domain 表示 api 归属的 group 域名后缀，比如 k8s 的部分域名归属于 "k8s.io"
Group 通常是全小写纯英文单词的组名，比如 apps，storage 等，如果 group 有多个单词组成，多个单词之间不允许使用连接符比如 . 或者 -，比如 apiextensions 这个 group 在代码生成的时候十分重要，会被采用为目录名和 go pacakge name
Group & Domain 这个是 k8s 中通常意义上的 group name，这里为了更好地区分，对它单独给出定义
它是由 Group + Domain 组合形成，成为一个完整的 dns subdomain，比如 "policy.k8s.io", "widget.mycompany.com"
但是不要使用下面的几种格式，它们是为 kubernetes 预留的 group
  1. empty group
  2. 一个单词的 group，比如 apps，extensions 等
  3. 以 k8s.io 为结尾的 group 域名 | | Version | 版本号，有意义的版本号如下 • v1, v2, v10 等表示正式的版本，多个版本之间可能不兼容 • v1alpha1, v2alpha2 表示 alpha 版本，这个版本表示 api 还不稳定，随时可能发生不兼容的变更 • v1beta1, v2beta2 表示 beta 版本，这个版本表示 api 已经稳定，可以认为和正式版没有太大差别，不会有不兼容的修改 |

API 类别

Kinds 分为三大类

类型规范

type Pod struct {
    metav1.TypeMeta   `json:",inline"`
		metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec PodSpec `json:"spec,omitempty"`
    Status PodStatus `json:"status,omitempty"`
}

Types meta

所有的资源最终从 REST API 返回的时候，都需要能编码成 JSON 的形式，并且必须包含下面两个字段