【k8s基础篇】k8s基础1之API概念与http path

最新推荐文章于 2024-06-06 16:31:41 发布

oceanweave

最新推荐文章于 2024-06-06 16:31:41 发布

阅读量1.5k

点赞数

分类专栏： Kubernetes学习笔记文章标签： http kubernetes docker

本文链接：https://blog.csdn.net/qq_24433609/article/details/122999270

版权

Kubernetes学习笔记专栏收录该内容

69 篇文章 37 订阅

订阅专栏

参考

https://kubernetes.io/zh/docs/reference/using-api/api-concepts/
Kubernetes 权威指南之 Kubernetes API 详解

API 概念

注意：

以下所有大写字母，都代表变量（比如GROUP，VERSION，真实书写中要写 core ,v1等，NAMESPACE 要写自己定义的名字，比如 default）；

小写的代表类别，是固定不变的，比如 apis，namespaces

术语

大多数 Kubernetes API 资源类型都是对象：它们代表的是集群中某一概念的具体实例，例如一个 Pod 或名字空间

Kubernetes 一般会利用标准的 RESTful 术语来描述 API 概念：

资源类型（Resource Type） 是在 URL 中使用的名称（pods、namespaces、services）
所有资源类型都有具有一个 JSON 形式（其对象的模式定义）的具体表示，称作类别（Kind）
某资源类型的实例的列表称作 集合（Collection）
资源类型的单个实例被称作 资源（Resource）

资源类型作用域

所有资源类型要么是集群作用域的（/apis/GROUP/VERSION/*），这个意思就是该资源不属于某个固定namespace，比如 ClusterRole
要么是名字空间作用域的（/apis/GROUP/VERSION/namespaces/NAMESPACE/*），是该资源属于某个固定 ns，比如 Pod

名字空间作用域的资源类型会在其名字空间被删除时也被删除，并且对该资源类型的访问是由定义在名字空间域中的授权检查来控制的

资源的路径表示

集群作用域的资源：
- GET /apis/GROUP/VERSION/RESOURCETYPE - 返回指定资源类型的资源的集合
- GET /apis/GROUP/VERSION/RESOURCETYPE/NAME - 返回指定资源类型下名称为 NAME 的资源
名字空间作用域的资源：
- GET /apis/GROUP/VERSION/RESOURCETYPE - 返回所有名字空间中指定资源类型的全部实例的集合
- GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE - 返回名字空间 NAMESPACE 内给定资源类型的全部实例的集合
- GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME - 返回名字空间 NAMESPACE 中给定资源类型的名称为 NAME 的实例

资源的访问

由于名字空间（namespaces)本身是一个集群作用域的资源类型
- 因此可以通过 GET /api/v1/namespaces/ 检视所有名字空间的列表
- 使用 GET /api/v1/namespaces/NAME 查看特定名字空间的详细信息
几乎所有对象资源类型都支持标准的 HTTP 动词 - GET、POST、PUT、PATCH 和 DELETE。 Kubernetes 使用术语 list 来描述返回资源集合的操作，以便与返回单个资源的、通常称作 get 的操作相区分。
- 暂未看到 list 的例子，理解为就是新增个动作 List 获取 API 对象 list
某些资源类型有一个或多个子资源（Sub-resource），表现为对应资源下面的子路径：
- 集群作用域的子资源：GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCE
- 名字空间作用域的子资源：GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCE

例子

列举给定名字空间中的所有 Pods：

GET /api/v1/namespaces/test/pods
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {"resourceVersion":"10245"},
  "items": [...]
}

高效检测变更 watch

为了使客户端能够构造一个模型来表达集群的当前状态，所有 Kubernetes 对象资源类型都需要支持一致的列表和一个称作 watch 的增量变更通知信源（feed）
每个 Kubernetes 对象都有一个 resourceVersion 字段，代表该资源在下层数据库中存储的版本。
- https://kubernetes.io/zh/docs/reference/using-api/api-concepts/#resource-versions
- 检视资源集合（名字空间作用域或集群作用域）时，服务器返回的响应中会包含 resourceVersion 值，可用来向服务器发起 watch 请求
- 服务器会返回所提供的 resourceVersion 之后发生的所有变更（创建、删除和更新）。这使得客户端能够取回当前的状态并监视其变更，且不会错过任何变更事件
- 客户端的监视连接被断开时，可以从最后返回的 resourceVersion 重启新的监视连接，或者执行一个新的集合请求之后从头开始监视操作

例子

列举给定名字空间中的所有 Pods：

GET /api/v1/namespaces/test/pods
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {"resourceVersion":"10245"}, # 先获取到目前的存储版本
  "items": [...]
}

从资源版本 10245 开始，以 JSON 对象的形式接收所有创建、删除或更新操作的通知：

GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245 # 从此版本开始跟踪 watch
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
  "type": "ADDED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
}
{
  "type": "MODIFIED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "11020", ...}, ...}
}
...

注意:

给定的 Kubernetes 服务器只会保留一定的时间内发生的历史变更列表
使用 etcd3 的集群默认保存过去 5 分钟内发生的变更
当所请求的 watch 操作因为资源的历史版本不存在而失败
客户端必须能够根据返回的状态代码 410 Gone进行处理，清空其本地的缓存，重新执行 list 操作，并基于新的 list 操作所返回的 resourceVersion 来开始新的 watch 操作
大多数客户端库都能够提供某种形式的、包含此逻辑的工具。（在 Go 语言客户端库中，这一设施称作 Reflector，位于 k8s.io/client-go/cache 包中。)

其他功能

书签 bookmark
分块 limit continue
表格形式接收结果 Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1
ProtoBuf 形式
预运行 dry-run
资源删除
- ```
{
  "kind": "ConfigMap",
  "apiVersion": "v1",
  "metadata": {
    "finalizers": {"url.io/neat-finalization", "other-url.io/my-finalizer"},
    "deletionTimestamp": nil,
  }
}
```
- 当客户端首先删除某资源时，其 .metadata.deletionTimestamp 会被设置为当前时间。一旦 .metadata.deletionTimestamp 被设置，则对终结器（finalizers）执行动作的外部控制器就可以在任何时候、以任何顺序执行其清理工作。这里不强调顺序是因为很可能带来 .metadata.finalizers 被锁定的风险。 .metadata.finalizers 是一个共享的字段，任何具有相关权限的主体都可以对其执行重排序的操作。如果终结器列表要按顺序处理，则很可能导致负责列表中第一个终结器的组件要等待负责列表中排序靠后的终结器的组件的信号（可能是字段值变更、外部系统或者其他形式），从而导致死锁行为。在不对终结器顺序作强制要求的情况下，终结器可以自行排序，且不会因为其在列表中的顺序而引入任何不稳定因素。
  
  当最后一个终结器也被移除时，资源才真正从 etcd 中移除。
以上可参见：https://kubernetes.io/zh/docs/reference/using-api/api-concepts/