目录

Kubernetes API 开发(一)

本文宏观介绍 kubernetesAPI 各版本之间的联系以及 API 开发的原则。

API Overview

API 版本转换

Kubernetes 的 API 分为 InternalExternal 版本。apiserver 同时支持多个API Version,在为开发提供了很高的自由度的同时也对API版本间的转换提出了更高的鲁棒性要求。

多个 external 版本间的转换, internal 版本处于中心位置,所有版本的 API 都能够转换成 internal 版本,但是其他版本之间能相互转换。所有的 kubernetes 代码 internal 版本结构中进行操作,并在存入etcd 前转换成 external 版本。客户端必须使用 external 版本操作。

以下是一个假设的操作例子:

  1. 用户 POST Pod/api/v7beta1/…
  2. JSON unmarshall 为 v7beta1.Pod
  3. v7beta1.Pod 补充默认值
  4. v7beta1.Pod 转换成 api.Pod
  5. 校验 api.Pod 并返回错误
  6. api.Pod 转换成 v6.Pod (稳定版本)
  7. v6.Pod marshall 成 JSON 并写入 etcd

版本兼容

Kubernets 把 API 的版本前向和后向兼容作为最高优先级进行考虑。 想要做到兼容很难,以下几点是实现 API 兼容需要考虑的:

  • 如果添加一个新功能,一定要是非必须的,要让旧版本也能正常工作

  • 不要修改已有接口的定义,包括:

    • 默认值和默认行为,以及其包含的语义
    • 已有 API 类型的字段和值的解释
    • 字段是否是必须字段
    • 可修改字段不要变为非可修改字段
    • 非法字段不要变成合法字段

换个说法:

  1. 所有修改前成功调用的 API, 修改后也要能成功调用。
  2. 所有不涉及修改的 API 调用,行为和修改前一致。
  3. 使用修改后的 API,在和未修改的 apiserver 通信时,不会导致问题。
  4. API 修改支持在不同版本间转换,并不丢失信息。
  5. 旧版本的 client 不感知 server 端修改,仍然正常工作。
  6. 支持回退到之前不包含修改的 API 版本, 并且不影响没有使用修改部分代码的 client。所有被修改影响到的 API 对象能够隐式回退。

参考