命名规范
- 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状态码
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 错误原因
网友评论