API 资源使用REST模式,具体说明如下。
-
GET /<资源名的复数格式>:获得某一类型的资源列表,例如GET /pods 返回一个Pod资源列表。
-
POST /<资源名的复数格式>:创建一个资源,该资源来自用户提供的JSON对象。
-
GET /<资源名复数格式>/<名字>:通过给出的名称(Name)获得单个资源,例如GET /pods/first 返回一个名称为“first”的Pod。
-
DELETE /<资源名复数格式>/<名字>:通过给出的名字删除单个资源,删除选项(DeleteOptions)中可以指定的优雅删除(Grace Deletion)的时间(GracePeriodSeconds),该可选项表明了从服务端接收到删除请求到资源被删除的时间间隔(单位为秒)。不同的类别(Kind)可能为优雅删除时间(Grace Period)申明默认值。用户提交的优雅删除时间将覆盖该默认值,包括值为0的优雅删除时间。
-
PUT /<资源名复数格式>/<名字>:通过给出的资源名和客户端提供的JSON对象来更新或创建资源。
-
PATCH /<资源名复数格式>/<名字>:选择修改资源详细指定的域。
对于PATCH操作,目前Kubernetes API通过相应的HTTP首部“Content-Type”对其进行识别。
目前支持以下三种类型的PATCH操作。
-
JSON Patch, Content-Type: application/json-patch+json。在RFC6902的定义中,JSON Patch是执行在资源对象上的一系列操作,例如 {"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}。详情请查看RFC6902说明,网址为HTTPs://tools.ietf.org/html/rfc6902。
-
Merge Patch, Content-Type: application/merge-json-patch+json。在RFC7386的定义中,Merge Patch必须包含对一个资源对象的部分描述,这个资源对象的部分描述就是一个JSON对象。该JSON对象被提交到服务端,并和服务端的当前对象合并,从而创建一个新的对象。详情请查看RFC73862说明,网址为HTTPs://tools.ietf.org/html/rfc7386。
-
Strategic Merge Patch, Content-Type: application/strategic-merge-patch+json。Strategic Merge Patch是一个定制化的Merge Patch实现。接下来将详细讲解Strategic Merge Patch。
在标准的JSON Merge Patch中,JSON对象总是被合并(merge)的,但是资源对象中的列表域总是被替换的。通常这不是用户所希望的。例如,我们通过下列定义创建一个Pod资源对象:
spec:
containers:
- name: nginx
image: nginx-1.0
接着我们希望添加一个容器到这个Pod中,代码和上传的JSON对象如下所示:
PATCH /api/v1/namespaces/default/pods/pod-name
spec:
containers:
- name: log-tailer
image: log-tailer-1.0
如果我们使用标准的Merge Patch,则其中的整个容器列表将被单个的“log-tailer”容器所替换。然而我们的目的是两个容器列表能够合并。
为了解决这个问题,Strategic Merge Patch通过添加元数据到API对象中,并通过这些新元数据来决定哪个列表被合并,哪个列表不被合并。当前这些元数据作为结构标签,对于API对象自身来说是合法的。对于客户端来说,这些元数据作为Swagger annotations也是合法的。在上述例子中,向“containers”中添加“patchStrategy”域,且它的值为“merge”,通过添加“patchMergeKey”,它的值为“name”。也就是说,“containers”中的列表将会被合并而不是替换,合并的依据为“name”域的值。
此外,Kubernetes API添加了资源变动的“观察者”模式的API接口。
-
GET /watch/<资源名复数格式>:随时间变化,不断接收一连串的JSON对象,这些JSON对象记录了给定资源类别内所有资源对象的变化情况。
-
GET /watch/<资源名复数格式>/:随时间变化,不断接收一连串的JSON对象,这些JSON对象记录了某个给定资源对象的变化情况。
上述接口改变了返回数据的基本类别,watch动词返回的是一连串的JSON对象,而不是单个的JSON对象。并不是所有的对象类别都支持“观察者”模式的API接口,在后续的章节中将会说明哪些资源对象支持这种接口。
另外,Kubernetes还增加了HTTP Redirect与HTTP Proxy这两种特殊的API接口,前者实现资源重定向访问,后者则实现HTTP请求的代理。
原文链接:https://www.orchome.com/1359