API 公约

命名规范

• resource 集合必须是小写复数形式，kinds驼峰单数形式
• go 字段名CamelCase, json 字段名：camelCase， 除了首字母，其他部分必须匹配
• 其他参考：https://github.com/kubernetes/kubernetes/blob/64a0e0ee193a532cdcaf30330fe9937af0bbc4cd/docs/devel/api-conventions.md#naming-conventions

kinds

Objects

• 代表一个可以持久化的 resource
• 可以被create, update, delete
• eg: Pod, ReplicationController, Service, Namespace, Node

Lists

• resources 常用资源的集合
• 命名必须包含“List”后缀， 有metadata限制，每个List必须有“items"包含一个数组
• eg：PodList, ServiceList, NodeList

Simple

• 代表特殊的操作或者非存储的对象
• 有metadata限制

Resource

每个API请求和返回都会包含如下字段（请求中如果没填，会采用系统默认值）：

• kind
• apiVersion

Objects

每个嵌套的Object kind，必须 要有metadata字段，metadata 必须 包含以下字段

• namespace， label， dns需要使用到
• name 唯一名称
• uid， 集群内的唯一标识，name删除后可以重用，uid，集群内唯一

metadata其他字段

• resourceVersion：
  • 资源版本，用于并发控制，要更新时对比服务器上的版本号，如果相同，代表没人进行更新操作，可以更新成功。否则返回http 409
  • 每次修改resouceVersion都会被修改
  • 设置时，必须从server GET得到
• generation：生成的唯一序列号
• creationTimestamp：创建时间
• deletionTimestamp：删除时间
• labels 标签
• annotations 备注信息

Spec

设计规范，想要达到预期状态的描述，包含以下部分

• 用户配置
• 系统自动填充的默认值
• 初始化后，或者创建后被其他组件设置的值

Typical status properties(aka Condition)

Condition 代表最新观察到的object的状态

• Type: Ready, Succeeded, Failure, Unknown
• Status：True, False, Unknown
• LastHeartbeatTime unversioned.Time
• LastTransitionTime unversioned.Time
• Reason 简洁的最新状态显示
• Message 详细信息

Primitive types 变量类型

• 避免使用浮点数
• 所有的数值类型（uint32, int64）都会转化成float64，当精度超过 > 53bits 时，使用字符串
• 不能使用unsigned int，由于平台和库的解析不同原因
• 不要使用枚举，使用alias替代
• 不要使用api中的关键字
• 所有的整形字段必须使用go语言的(u)int32 or (u)int64 types，不能使用(u)int

Constants 常量

首字母大写驼峰式，替代枚举

union 类型

只能设置为其中的一个

Lists and Simple kinds

嵌套的metadata字段中必须包含resourceVersion，并行控制，和幂等性控制

api

• GET /<resourceNamePlural> 获取资源列表
• POST /<resourceNamePlural> 创建新的资源
• GET /<resourceNamePlural>/<name> 获取resoucrce 名称为name
• DELETE /<resourceNamePlural>/<name> 删除特定的资源，删除资源需要经过一定的时间
• PUT /<resourceNamePlural>/<name> 创建或者更新资源
• PATCH /<resourceNamePlural>/<name> 修改特定的字段
• GET /<resourceNamePlural>&watch=true 订阅，接收修改的信息

PATCH 修改操作

根据Content-Type有三种PATCH操作：

JSON Patch, Content-Type: application/json-patch+json

• eg:{"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}
• 语法手册：https://tools.ietf.org/html/rfc6902

Merge Patch, Content-Type: application/merge-patch+json

• 替换已经存在的值
• 手册和例子： https://tools.ietf.org/html/rfc7386

Strategic Merge Patch, Content-Type: application/strategic-merge-patch+json

• 自定义替换的策略，入list采用合并，而不是替换
  • 列表操作覆盖替换

  containers:
  - name: nginx
    image: nginx-1.0
  - $patch: replace  
  

  • 列表删除

  containers:
  - name: nginx
    image: nginx-1.0
  - $patch: delete
    name: log-tailer  # merge key and value goes here
  

  • map merge

  $patch: replace  # recursive and applies to all fields of the map it's in
  containers:
  - name: nginx
    image: nginx-1.0
  

  • map 删除某个字段的值

  name: nginx
  image: nginx-1.0
  labels:
    live: null  # set the value of the map key to null
  

http状态码

https://github.com/kubernetes/kubernetes/blob/64a0e0ee193a532cdcaf30330fe9937af0bbc4cd/docs/devel/api-conventions.md#http-status-codes

Response Status Kind 返回结果的kind是Status类型

返回Status的两种情况

• http 状态码，非20x
• http delte 操作成功

返回包体

{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {},
  "status": "Failure",
  "message": "pods \"grafana\" not found",
  "reason": "NotFound",
  "details": {
    "name": "grafana",
    "kind": "pods"
  },
  "code": 404
}

• status: Success, Failure
• message: 错误详情
• reason： machine-readable 错误原因