Kubernetes API 概念

Kubernetes API 概念

本页描述 Kubernetes API 的通用概念。

Kubernetes API 是基于资源的（RESTful）、通过 HTTP 提供的编程接口。 API 支持通过标准的 HTTP 动词（POST、PUT、PATCH、DELETE 和 GET）检视、创建、更新和删除主要资源，为很多允许细粒度权限控制的对象提供子资源（如将 Pod 绑定到节点上），并且出于便利性或效率考虑，支持并提供这些资源的不同表示形式。 Kubernetes API 还通过 “watch” 和一致性的列表支持高效的资源变更通知，从而允许其他组件对资源的状态进行高效的缓存和同步。

标准 API 术语

大多数 Kubernetes API 资源类型都是对象：它们代表的是集群中某一概念的具体实例，例如一个 Pod 或名字空间。为数不多的几个 API 资源类型是“虚拟的” - 它们通常代表的是操作而非对象本身，例如访问权限检查（使用 POST 请求发送一个 JSON 编码的 SubjectAccessReview 负载到 subjectaccessreviews 资源）。所有对象都有一个唯一的名字，以便支持幂等的创建和检视操作，不过如果虚拟资源类型不可检视或者不要求幂等，可以不具有唯一的名字。

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

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

所有资源类型要么是集群作用域的（/apis/GROUP/VERSION/*），要么是名字空间作用域的（/apis/GROUP/VERSION/namespaces/NAMESPACE/*）。名字空间作用域的资源类型会在其名字空间被删除时也被删除，并且对该资源类型的访问是由定义在名字空间域中的授权检查来控制的。下列路径用来检视集合和资源：

集群作用域的资源：
- 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 的实例

由于名字空间本身是一个集群作用域的资源累;，你可以通过 GET /api/v1/namespaces/ 检视所有名字空间的列表，使用 GET /api/v1/namespaces/NAME 查看特定名字空间的详细信息。

几乎所有对象资源类型都支持标准的 HTTP 动词 - GET、POST、PUT、PATCH 和 DELETE。 Kubernetes 使用术语 list 来描述返回资源集合的操作，以便与返回单个资源的、通常称作 get 的操作相区分。

某些资源类型有一个或多个子资源（Sub-resource），表现为对应资源下面的子路径：

集群作用域的子资源：GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCE
名字空间作用域的子资源：GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCE

取决于对象是什么，每个子资源所支持的动词有所不同 - 参见 API 文档以了解更多信息。跨多个资源来访问其子资源是不可能的 - 如果需要这一能力，则通常意味着需要一种新的虚拟资源类型了。

高效检测变更

为了使客户端能够构造一个模型来表达集群的当前状态，所有 Kubernetes 对象资源类型都需要支持一致的列表和一个称作 watch 的增量变更通知信源（feed）。每个 Kubernetes 对象都有一个 resourceVersion 字段，代表该资源在下层数据库中存储的版本。检视资源集合（名字空间作用域或集群作用域）时，服务器返回的响应中会包含 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
---
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 包中。)

监视书签（Watch Bookmark）

为了处理历史窗口过短的问题，我们引入了 bookmark（书签） 监视事件的概念。该事件是一种特殊事件，用来标示客户端所请求的、指定的 resourceVersion 之前的所有变更都以被发送。该事件中返回的对象是所请求的资源类型，但其中仅包含 resourceVersion 字段，例如：

GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json
{
  "type": "ADDED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
}
...
{
  "type": "BOOKMARK",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
}

通过在 watch 请求中设置 allowWatchBookmarks=true 选项，可以请求 bookmark 事件，但是客户端不能假定服务器端会按某特定时间间隔返回书签事件，甚至也不能假定服务器一定会发送 bookmark 事件。

分块检视大体量结果

FEATURE STATE: Kubernetes v1.9 [beta]

在较大规模的集群中，检视某些资源类型的集合时可能会返回较大体量的响应数据，对服务器和客户端都会造成影响。例如，某集群可能包含数万个 Pod，每个 Pod 的 JSON 编码都有 1-2 KB 的大小。返回所有名字空间的全部 Pod 时，其结果可能体量很大（10-20 MB）且耗用大量的服务器资源。从 Kubernetes 1.9 开始，服务器支持将单一的大体量集合请求分解成多个小数据块同时还保证整个请求的一致性的能力。各个数据块可以按顺序返回，进而降低请求的尺寸，允许面向用户的客户端以增量形式呈现返回结果，改进系统响应效果。

为了用分块的形式返回一个列表，集合请求上可以设置两个新的参数 limit 和 continue，并且所有 list 操作的返回结果列表的 metadata 字段中会包含一个新的 continue 字段。客户端应该将 limit 设置为希望在每个数据块中收到的结果个数上限，而服务器则会在结果中至多返回 limit 个资源并在集合中还有更多资源的时候包含一个 continue 值。客户端在下次请求时则可以将此 continue 值传递给服务器，告知后者要从何处开始返回结果的下一个数据块。通过重复这一操作直到服务器端返回空的 continue 值，客户端可以受到结果的全集。

与 watch 操作类似，continue 令牌也会在很短的时间（默认为 5 分钟）内过期，并在无法返回更多结果时返回 410 Gone 代码。这时，客户端需要从头开始执行上述检视操作或者忽略 limit 参数。

例如，如果集群上有 1253 个 Pods，客户端希望每次收到包含至多 500 个 Pod 的数据块，它应按下面的步骤来请求数据块：

列举集群中所有 Pod，每次接收至多 500 个 Pods：

GET /api/v1/pods?limit=500
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "ENCODED_CONTINUE_TOKEN",
    ...
  },
  "items": [...] // returns pods 1-500
}

继续前面的调用，返回下一组 500 个 Pods：

GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "ENCODED_CONTINUE_TOKEN_2",
    ...
  },
  "items": [...] // returns pods 501-1000
}

继续前面的调用，返回最后 253 个 Pods：

GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "", // continue token is empty because we have reached the end of the list
    ...
  },
  "items": [...] // returns pods 1001-1253
}

注意 list 操作的 resourceVersion 在每个请求中都设置的是同一个数值，这表明服务器要向我们展示一个一致的 Pods 快照视图。在版本 10245 之后创建、更新或删除的 Pods 都不会显示出来，除非用户发出 list 请求时不指定 continue 令牌。这一设计使得客户端能够将较大的响应切分为较小的数据块，且能够对较大的集合执行监视动作而不会错失任何更新事件。

以表格形式接收资源

kubectl get 命令的输出是一个包含一个或多个资源的简单表格形式。过去，客户端需要重复 kubectl 中所实现的表格输出和描述输出逻辑，以执行简单的对象列表操作。这一方法在处理某些对象时，需要引入不容忽视的逻辑。此外，API 聚合和定制资源所提供的资源类型都是编译时不可预知的。这意味着，客户端必须针对无法识别的类型提供通用的实现逻辑。

为了避免上述各种潜在的局限性，客户端可以请求服务器端返回对象的表格（Table）表现形式，从而将打印输出的特定细节委托给服务器。 Kubernetes API 实现标准的 HTTP 内容类型（Content Type）协商：为 GET 调用传入一个值为 application/json;as=Table;g=meta.k8s.io;v=v1beta1 的 Accept 头部即可请求服务器以 Table 的内容类型返回对象。

例如，以 Table 格式列举集群中所有 Pods：

GET /api/v1/pods
Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1
---
200 OK
Content-Type: application/json
{
    "kind": "Table",
    "apiVersion": "meta.k8s.io/v1beta1",
    ...
    "columnDefinitions": [
        ...
    ]
}

对于在服务器上不存在定制的 Table 定义的 API 资源类型而言，服务器会返回一个默认的 Table 响应，其中包含资源的 name 和 creationTimestamp 字段。

GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
---
200 OK
Content-Type: application/json
...
{
    "kind": "Table",
    "apiVersion": "meta.k8s.io/v1beta1",
    ...
    "columnDefinitions": [
        {
            "name": "Name",
            "type": "string",
            ...
        },
        {
            "name": "Created At",
            "type": "date",
            ...
        }
    ]
}

kube-apiserver 从 1.10 版本开始提供 Table 响应。因此，并非所有 API 资源类型都支持 Table 响应，尤其是使用客户端访问较老的集群时。如果客户端需要能够处理所有资源类型，或者有可能需要与较老的集群交互，则需要在其 Accept 头部设定多个内容类型值，以便可以回退到非表格形式的 JSON 表示。

Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1, application/json

资源的其他表示形式

默认情况下，Kubernetes 返回 JSON 序列化的的对象并设定内容类型为 application/json。这是 API 的默认序列化格式。不过，客户端也可出于大规模环境中更佳性能的需求而请求对象的更为高效的 Protobuf 表现形式。 Kubernetes API 实现了标准的 HTTP 内容类型协商：为 GET 调用传递一个 Accept 头部来请求服务器以所指定的内容类型返回对象，同时在通过 PUT 或 POST 调用向服务器发送 Protobuf 格式的对象时提供 Content-Type 头部。服务器会能够支持所请求的格式时返回 Content-Type 头部，并在所提供的内容类型不合法时返回 406 Not acceptable（无法接受） 错误。

请参阅 API 文档了解每个 API 所支持的内容类型。

例如：

以 Protobuf 格式列举集群上的所有 Pods：

GET /api/v1/pods
Accept: application/vnd.kubernetes.protobuf
---
200 OK
Content-Type: application/vnd.kubernetes.protobuf
... binary encoded PodList object

通过向服务器发送 Protobuf 编码的数据创建 Pod，但请求以 JSON 形式接收响应：

POST /api/v1/namespaces/test/pods
Content-Type: application/vnd.kubernetes.protobuf
Accept: application/json
... binary encoded Pod object
---
200 OK
Content-Type: application/json
{
  "kind": "Pod",
  "apiVersion": "v1",
  ...
}

并非所有 API 资源类型都支持 Protobuf，尤其是那些通过定制资源定义（CRD）或通过 API 扩展而加入的资源。如果客户端必须能够处理所有资源类型，则应在其 Accept 头部指定多种内容类型以便可以回退到 JSON 格式：

Accept: application/vnd.kubernetes.protobuf, application/json

Protobuf encoding

Kubernetes 使用封套形式来对 Protobuf 响应进行编码。封套外层由 4 个字节的特殊数字开头，便于从磁盘文件或 etcd 中辩识 Protobuf 格式的（而不是 JSON）数据。接下来存放的是 Protobuf 编码的封套消息，其中描述下层对象的编码和类型，最后才是对象本身。

封套格式如下：

四个字节的特殊数字前缀：
  字节 0-3: "k8s\x00" [0x6b, 0x38, 0x73, 0x00]
使用下面 IDL 来编码的 Protobuf 消息：
  message Unknown {
    // typeMeta 应该包含 "kind" 和 "apiVersion" 的字符串值，就像
    // 对应的 JSON 对象中所设置的那样
    optional TypeMeta typeMeta = 1;
    // raw 中将保存用 protobuf 序列化的完整对象。
    // 参阅客户端库中为指定 kind 所作的 protobuf 定义
    optional bytes raw = 2;
    // contentEncoding 用于 raw 数据的编码格式。未设置此值意味着没有特殊编码。
    optional string contentEncoding = 3;
    // contentType 包含 raw 数据所采用的序列化方法。
    // 未设置此值意味着  application/vnd.kubernetes.protobuf，且通常被忽略
    optional string contentType = 4;
  }
  message TypeMeta {
    // apiVersion 是 type 对应的组名/版本
    optional string apiVersion = 1;
    // kind 是对象模式定义的名称。此对象应该存在一个 protobuf 定义。
    optional string kind = 2;
  }

收到 application/vnd.kubernetes.protobuf 格式响应的客户端在响应与预期的前缀不匹配时应该拒绝响应，因为将来的版本可能需要以某种不兼容的方式更改序列化格式，并且这种更改是通过变更前缀完成的。

资源删除

资源删除要经过两个阶段：1) 终止（finalization），和 2）去除。

{
  "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 中移除。

单个资源 API

API 动词 GET、CREATE、UPDATE、PATCH、DELETE 和 PROXY 仅支持单个资源。这些支持单一资源的动词不支持以有序或无序列表甚或事务的形式同时提交给多个资源。包括 kubectl 在内的客户端将解析资源的列表，并执行单一资源的 API 请求。

API 动词 LIST 和 WATCH 支持获取多个资源，而 DELETECOLLECTION 支持删除多个资源。

试运行

FEATURE STATE: Kubernetes v1.18 [stable]

修改性质的动词（POST、PUT、PATCH 和 DELETE）可以支持 试运行（dry run） 模式的请求。试运行模式可帮助通过典型的请求阶段（准入控制链、合法性检查、合并冲突）来评估请求，只是最终的对象不会写入存储。请求的响应主体与非试运行模式下的响应尽可能接近。系统会保证试运行模式的请求不会被写入到存储中，也不会产生其他副作用。

发起试运行请求

通过设置 dryRun 查询参数可以触发试运行模式。此参数是一个字符串，以枚举值的形式工作且可接受的值只有：

All：每个阶段被会正常运行，除了最后的存储阶段。准入控制器会被运行来检查请求是否合法，变更性（Mutating）控制器会变更请求，PATCH 请求也会触发合并操作，对象字段的默认值也会被设置，且基于模式定义的合法性检查也会被执行。所生成的变更不会被写入到下层的持久性存储中，但本来会写入到数据库中的最终对象会和正常的状态代码一起被返回给用户。如果请求会触发准入控制器而该准入控制器带有一定的副作用，则请求会失败而不是冒险产生不希望的副作用。所有的内置准入控制器插件都支持试运行模式。此外，准入控制 Webhook 也可在其配置对象中通过将 sideEffects 字段设置为 “None” 来声明自身不会产生副作用。如果某 Webhook 确实会产生副作用，那么 sideEffects 字段应该设置为 “NoneOnDryRun”，并且 Webhook 应该被更改以支持 AdmissionReview 中的 dryRun 字段，从而避免在试运行时产生副作用。
空字符串（也即默认值）：保留默认的修改行为。

例如：

POST /api/v1/namespaces/test/pods?dryRun=All
Content-Type: application/json
Accept: application/json

响应会与非试运行模式请求的响应看起来相同，只是某些生成字段的值可能会不同。

试运行的授权

试运行和非试运行请求的鉴权是完全相同的。因此，要发起一个试运行请求，用户必须被授权执行非试运行请求。

例如，要在 Deployment 对象上试运行 PATCH 操作，你必须具有对 Deployment 执行 PATCH 操作的访问权限，如下面的 RBAC 规则所示：

rules:
- apiGroups: ["extensions", "apps"]
  resources: ["deployments"]
  verbs: ["patch"]

参阅鉴权概述以了解鉴权细节。

生成的值

对象的某些值通常是在对象被写入数据库之前生成的。很重要的一点是不要依赖试运行请求为这些字段所设置的值，因为试运行模式下所得到的这些值与真实请求所获得的值很可能不同。这类字段有：

name：如果设置了 generateName 字段，则 name 会获得一个唯一的随机名称
creationTimestamp/deletionTimestamp：记录对象的创建/删除时间
UID：唯一性标识对象，取值随机生成（非确定性）
resourceVersion：跟踪对象的持久化（存储）版本
变更性准入控制器所设置的字段
对于 Service 资源：kube-apiserver 为 v1.Service 对象分配的端口和 IP

服务器端应用

FEATURE STATE: Kubernetes v1.16 [beta]

从 Kubernetes v1.18 开始，如果你启动了服务器端应用（Service Side Apply）功能特性，则控制面会跟踪所有新创建的对象的托管字段（Managed Fields）。

介绍

服务器端应用可以通过声明式配置帮助用户和控制器管理其资源。此功能特性允许用户和控制器通过将完全设定的意愿发送到服务器以声明式方式创建与/或更改其对象。

完全设定的意愿（Fully Specified Intent）是对象的一个部分，仅包含用户希望表达其意愿的字段和取值。此意愿或者是要创建一个新的对象，或者是由服务器来负责完成的、与现有对象的合并。

系统支持多个施加者（Applier）同一个对象上进行协作。

对对象字段的变更是通过“字段管理”来进行跟踪的。当字段的值发生变化时，其属主从其当前的管理器切换为作出变更的管理器。尝试应用对象时，取值不同的字段以及由另一个管理器所拥有的字段都会导致冲突。引发冲突的目的是通告该操作可能会撤销掉另一协作方所做的变更。冲突可以被强制解决，从而导致字段取值被覆盖且其属主关系被转移。

如果你从配置中去除了一个字段并应用该配置，服务器端应用组件会检查是否有其他字段管理器也拥有该字段。如果该字段不再被任何其他字段管理器所拥有，则或者它会被从现时对象上删除，或者会被重置为其默认值（假设有的话）。同样的规则也适用于关联列表或映射条目。

服务器端应用旨在成为原来的 kubectl apply 的替代技术，同时也作为控制器来施加其变更的一种更简单的机制。

字段管理

与 kubectl 所管理的 last-applied 注解相比，服务器端应用机制使用的是一种更为贴近声明式管理的方法。该方法会跟踪用户的字段管理而不是其上一次应用的状态。这就意味着，作为服务器端应用的一种副作用，关于哪个字段管理器管理对象中哪个字段的信息也变得透明。

从服务器端应用的角度，让用户来管理字段意味着用户可以相信并期望字段不会发生变更。上次对某字段取值做出断言的用户会被记录为当前的字段管理器。这一记录操作可以通过使用 POST、PUT 或非应用性（non-apply）的 PATCH 去更改字段值来实现，或者将字段包含在发送该服务器端应用末端的配置中来实现。当使用服务器端应用特性时，尝试更给由其他人所管理的字段会导致请求被拒绝（这里指非强制应用场景，参见冲突）。

当两个或者多个施加者将某字段设置为相同的值，它们会共享字段的属主地位。由任何施加者所发起的、尝试变更共享字段取值的请求都会导致冲突。共享字段的属主可以通过将字段从其配置中去除来放弃其属主角色。

字段管理信息保存在 managedFields 字段中，而该字段是对象 metadata 的一部分。

通过服务器端应用创建的对象的一个简单例子看起来可能像这样：

apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
  namespace: default
  labels:
    test-label: test
  managedFields:
  - manager: kubectl
    operation: Apply
    apiVersion: v1
    time: "2010-10-10T0:00:00Z"
    fieldsType: FieldsV1
    fieldsV1:
      f:metadata:
        f:labels:
          f:test-label: {}
      f:data:
        f:key: {}
data:
  key: some value

上面的对象在其 metadata.managedFields 中包含了唯一的管理器。管理器记录中包含了管理实体自身的一些基本信息，例如操作类型、API 版本以及所管理的字段。

此字段由 API 服务器管理，因而不应被用户修改。

尽管如此，通过 Update 操作来更改 metadata.managedFields 字段值还是可能的。这样做是非常不鼓励的，但在某些场合也可能是一种合理的选择。例如，managedFields 陷入了某种不一致的状态（很明显这种事不应该发生）。

managedFields 的格式在API 中有详细描述。

冲突

冲突是一种特殊的状态错误，发生在某 Apply 操作尝试变更某字段，而另一个用户也声称要管理之的时候。冲突的检测可以避免某一施加者不小心覆盖另一个用户所设置的字段值。当发生冲突时，解决它的方法有三种：

覆盖字段值，成为唯一的管理器： 如果有意要覆盖字段值（或者施加者本身是一个控制器这种自动化进程），施加者应该设置查询参数 force 为 true，并再次发出请求。这样做会强迫操作成功，更改字段值，将字段从 managedFields` 中其他管理器项中去除。
不重载字段值，放弃管理主张： 如果施加者不再关心字段取值，它们可以将字段从其配置中删除并再次发出请求。这样做会保留字段值不变，同时从 managedFields 中施加者条目中删除该字段。
不重载字段值，成为共享管理器： 如果施加者仍然关心字段取值，但不想重载其当前值，它可以将其配置中该字段的值更改为与服务器端对象上的值匹配，并再次发出请求。这样做会保留字段取值不变，同时使得字段的管理权力被施加者以及所有原来声称要管理该字段的其他字段管理器一起分享。

管理器

管理器标示更改对象的不同工作流（尤其是在有冲突的场合），可以作为更改对象的请求的一部分，在 fieldManager 查询参数中设定。该参数对于 Apply 操作的端点是必需的，尽管 kubectl 会将其默认设置为 kubectl。对于其他更新操作，其默认值是基于用户代理（User-agent）计算而来的。

应用与更新

服务器端应用所考虑的两种操作分别是 Apply （内容类型设置为 application/apply-patch+yaml 的 PATCH 操作）和 Update（所有其他会更改对象的操作）。这两种操作都会更新 managedFields 字段值，但其行为略有不同。

说明：

无论你所提交的是 JSON 数据或者 YAML 数据，都应将 Content-Type 头部字段的值设置为 application/apply-patch+yaml。

所有 JSON 文档也都是合法的 YAML 文档。

例如，发生冲突时只有 Apply 操作会失败，而 Update 操作不会失败。还有，Apply 操作要求通过提供一个 fieldManager 查询参数来标识自身，而对于 Update 操作而言，这一查询参数是可选的。最后，使用 Apply 操作时，被应用的对象中不能包含 managedFields 字段。

带有多个管理器的一个对象示例可能看起来是这个样子：

apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
  namespace: default
  labels:
    test-label: test
  managedFields:
  - manager: kubectl
    operation: Apply
    apiVersion: v1
    fields:
      f:metadata:
        f:labels:
          f:test-label: {}
  - manager: kube-controller-manager
    operation: Update
    apiVersion: v1
    time: '2019-03-30T16:00:00.000Z'
    fields:
      f:data:
        f:key: {}
data:
  key: new value

在此例中，第二个操作是由一个称作 kube-controller-manager 的管理器所发起的 Update 执行的。该 Update 操作更改了 data 字段的值，导致该字段的管理者被更改为 kube-controller-manager。

说明： 如果此操作是一个 Apply 操作，则操作可能已因为属主冲突而失败。

合并策略

服务器端应用所实现的合并策略能够支持相对更为稳定的对象生命周期。服务器端应用机制尝试基于字段的管理器是谁来合并字段而不是仅仅基于字段取值来判断。这种机制旨在通过减少意外的干扰而将多个主体更新同一对象的操作变得更为简单和稳定。

当用户发送一个“完全指定的意愿”对象到服务器端应用端点，如果字段值同时出现在现时对象中和所给的意愿对象中，服务器会优先选择应用配置中的字段值。如果应用的配置中存在的条目集合不是同一用户上次应用的条目集合的超集，所有未被其他施加者管理的、在应用的配置中缺失的条目都会被移除。关于如何使用对象的模式定义（Schema）来决定合并行为的更多信息，可参阅 sigs.k8s.io/structured-merge-diff。

Kubernetes 1.16 和 1.17 中都添加了若干的标志（Markers），便于 API 开发人员描述 list、map 和 struct 所支持的合并策略。这些标志可以应用到 Go 文件中对应类型的对象或者 CRD 的 OpenAPI 模式定义：

Golang 标志	OpenAPI 扩展	可接受的值	描述	引入版本
`//+listType`	`x-kubernetes-list-type`	`atomic`/`set`/`map`	可应用到 list 类型。`atomic` 和 `set` 适用于仅包含标量的 list。`map` 适用于由内嵌类型组成的 list。如果配置为 `atomic`，则整个 list 会在合并时被替换掉；每次只会有一个管理器负责总体管理这个 list。如果配置为 `granular`，则不同的管理器可以分别管理不同的表项。	1.16
`//+listMapKey`	`x-kubernetes-list-map-keys`	由 map 主键构成的可唯一标识表项的切片，例如 `[“port”, “protocol”]`	仅当标记了 `+listType=map` 时适用。切片中各个字符串对应的取值的组合必须能够唯一性地标识 list 中的表项。尽管主键可以有多个，由于在 Go 语言类型中每个键需要独立设置，这里的 `listMapKey` 是单数形式。	1.16
`//+mapType`	`x-kubernetes-map-type`	`atomic`/`granular`	适用于 map 类型。`atomic` 意味着 map 只能被某管理器整体替换。`granular` 则意味着 map 支持使用不同管理器来更新不同字段。	1.17
`//+structType`	`x-kubernetes-map-type`	`atomic`/`granular`	适用于 struct 类型。除此以外，其用法和 OpenAPI 注解都与 `//+mapType` 相同。	1.17

定制资源

默认情况下，服务器端应用机制会将定制资源视为无结构的数据。其中所有键都会被视同 struct 的字段，而所有 list 都会被视为 atomic。

如果定制资源定义（CRD）定义了包含如合并策略节所述的注解的模式定义（Schema），则在合并该类型对象时会使用到这些注解。

在控制器中使用服务器端应用机制

作为控制器的开发人员，你可以将服务器端应用机制作为一种方法来简化你的控制器中的更新逻辑。与“读出-更改-写回”或“读出-更改-打补丁”方式相比，区别如下：

所应用的对象必需包含控制器所关心的所有字段；
没有办法移除控制器之前未曾应用过的字段（控制器在这些使用场景中仍然可以发送一个 PATCH/UPDATE 请求）。
对象不需要事先读出，且不必指定 resourceVersion 值。

强烈建议控制器总是“强制解决”冲突，因为它们可能无法更好地解决或者处理这些冲突。

转移属主关系

除了冲突解决机制所提供的并发控制外，服务器端应用机制还提供了一些方法，通过协作式途径将字段属主从用户转移到控制器。

这一转移操作最好通过示例来阐明。我们来看如何安全地将 replicas 字段的属主从一个用户转移给一个控制器，同时允许使用 HorizontalPodAutoscaler 资源及其相配套的控制器为 Deployment 提供自动的水平扩缩。

假定一个用户定义了一个 Deployment，并将其 replicas 设置为其期望值：

application/ssa/nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2

用户使用服务器端应用机制创建了 Deployment：

kubectl apply -f application/ssa/nginx-deployment.yaml --server-side

再接下来，为 Deployment 启用了 HPA，例如：

kubectl autoscale deployment nginx-deployment --cpu-percent=50 --min=1 --max=10

现在，用户希望将 replicas 从其配置中移除，这样它们就不会与 HPA 控制器产生冲突。不过，仍然会有竞争条件出现：在 HPA 觉得需要调整 replicas 之前可能还有一段时间。如果用户在向 replicas 字段写入新值进而成为其属主之前，已经从配置中移除了该字段，则 API 服务器会将 replicas 设置为 1，也就是该字段的默认值。这一复位操作并非用户希望发生的事情，即使是临时性的复位也不可以。

解决方案有两种：

（较容易的方案）在配置中保留 replicas，当 HPA 终于向该字段中写入取值时，系统会向用户报告一个冲突事件。在这一刻，从配置中移除该字段是相对安全的。
（更高级的方案）如果用户不想等待 HPA 写入字段值的事件，例如他们希望集群状态对他们的同事而言也是清晰明确的，则他们可以采取以下步骤安全地从他们的配置中移除 replicas 字段。

首先，用户定义一个新的，仅包含 replicas 字段的配置：

application/ssa/nginx-deployment-replicas-only.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3

接下来使用名为 handover-to-hpa 的字段管理器应用该配置：

kubectl apply -f application/ssa/nginx-deployment-replicas-only.yaml --server-side --field-manager=handover-to-hpa --validate=false

如果应用操作与 HPA 控制器发生冲突，则什么也不做。冲突恰好表明控制器比平时早了一点发出对该字段的主张：

这时，用户可以从其配置中删除 replicas 字段。

application/ssa/nginx-deployment-no-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2

注意，无论 HPA 控制器何时将 replicas 字段设置为新的取值，临时性的字段管理器都不再拥有任何字段，并且会被自动删除。用户不需要执行清理操作。

在用户间移交属主角色

用户之间可以通过在他们所应用的配置中将字段设置为相同的值来转移字段属主关系，这样做会共享对字段的拥有权。一旦用户间共享了字段的属主关系，其中一个用户就可以从其所应用的配置中移除该字段，放弃属主角色，从而完成了属主关系的移交。

与客户端应用的比较

服务器端应用机制所实现的冲突检测和解决方案的后果之一是施加者在其本地状态中总是能够看到最新的字段值。如果他们看不到，则在下次执行 Apply 操作时会收到冲突事件。解决冲突的三种方法中，任何一种都会让所应用的配置成为服务器端对象字段的最新子集。

这点与客户端应用不同，施加者本地配置中保留的可能是已经被其他用户更改过了的过时的取值。只有用户更新该字段时，相应的字段值才会变得准确。施加者也无法知道他们下次执行 Apply 操作时是否会重载其他用户做出的变更。

另外一点区别在于使用客户端应用的施加者无法更改他们所使用的 API 版本，但是服务器端应用能够支持这种使用场景。

从客户端应用升级到服务器端应用

客户端应用机制的用户如果在使用 kubectl apply 来管理资源，可以使用下面的标志来开始使用服务器端应用：

kubectl apply --server-side [--dry-run=server]

默认情况下，对象的字段管理会从客户端应用转移到 kubectl 服务器端应用，且不会出现冲突状况。

注意：

请保持 last-applied-configuration 注解内容是最新的。该注解用来推测客户端应用所管理的字段。所有没有被客户端应用管理的字段都会引发冲突。

例如，如果你在客户端应用操作后使用 kubectl scale 命令更新了 replicas 字段，该字段不再由客户端应用所拥有，在 kubectl apply --server-side 时会引发冲突。

此行为适用于使用 kubectl 字段管理器执行的服务器端应用。作为一种例外情况，你也可以选择不采用这种行为，而是像下面的例子中所给的那样，指定一个不同的、非默认的字段管理器。用 kubectl 来执行服务器端应用时，默认的字段管理器总是 kubectl。

kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

从服务器端应用降格为客户端应用

如果你使用 kubectl apply --server-side 来管理资源，你可以直接使用 kubectl apply 来降格到客户端应用机制。

降格操作之所以能够有效是因为 kubectl 服务器端应用在你使用 kubectl apply 时会保持 last-applied-configuration 注解内容一直是最新的。

这一行为适用于使用 kubectl 字段管理器执行的服务器端应用。作为一种例外情况，你也可以选择不采用这种默认行为，而像下面例子中所展示的那样，设置一个不同的、非默认的字段管理器。kubectl 所触发的服务器端应用默认会将字段管理器设置为 kubectl。

kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

API 端点

启用了服务器端应用功能特性之后，PATCH 操作的端点能够接受 application/apply-patch+yaml 内容类型。服务器端应用机制的用户可以以 YAML 格式将部分设定的对象发送到该端点。在应用配置时，用户应该包含希望设置的所有字段在内。

清除 `managedFields`

通过 MergePatch、StrategicMergePatch、JSONPatch 或 Update 等非 Apply 操作是可以清除对象上的所有 managedFields 内容的。通过这些操作，用户可以将 managedFields 字段重新设置为空的列表。下面是两个例子：

PATCH /api/v1/namespaces/default/configmaps/example-cm
Content-Type: application/merge-patch+json
Accept: application/json
Data: {"metadata":{"managedFields": [{}]}}

PATCH /api/v1/namespaces/default/configmaps/example-cm
Content-Type: application/json-patch+json
Accept: application/json
Data: [{"op": "replace", "path": "/metadata/managedFields", "value": [{}]}]

上面的操作会覆盖 managedFields 字段取值，使之成为一个只有一个空表项的列表，进而使得 managedFields 整个会被充对象上剥离。注意，仅仅将 managedFields 设为空列表还不足以将字段取值复位。这样的设计是有意为之的，目的是避免 managedFields 字段被不了解该字段的客户端意外清除。

如果此复位操作和对 managedFields 字段之外的其它字段的变更一起提交，则 managedFields 的内容会首先被重置，之后才会处理其他字段变更。因此，施加者会成为同一请求中被更新的字段的属主。

注意： 服务器端应用机制无法正确地跟踪某些子资源的属主，如果这些子资源不能接收资源对象类型数据的话。如果你针对这类子资源使用服务器端应用机制，则所变更的字段不会被跟踪记录。

禁用此功能特性

服务器端应用是一种 Beta 阶段的特性，因此默认是被启用的。如要将此特性门控关闭，你需要在启动 kube-apiserver 时包含 --feature-gates ServerSideApply=false 标志。如果你运行了多个 kube-apiserver 副本，则每个副本上都要作同样的标志设置。

资源版本

资源版本采用字符串来表达，用来标示对象的服务器端内部版本。客户端可以使用资源版本来判定对象是否被更改，或者在读取、列举或监视资源时用来表达数据一致性需求。客户端必需将资源版本视为不透明的对象，将其原封不动地传递回服务器端。例如，客户端一定不能假定资源版本是某种数值标识，也不可以对两个资源版本值进行比较看其是否相同（也就是不可以比较两个版本值以判断其中一个比另一个大或小）。

`metadata` 中的 `resourceVersion`

客户端可以在资源中看到资源版本信息，这里的资源包括从服务器返回的 Watch 事件以及 list 操作响应：

v1.meta/ObjectMeta - 资源的 metadata.resourceVersion 值标明该实例上次被更改时的资源版本。

v1.meta/ListMeta - 资源集合（即 list 操作的响应）的 metadata.resourceVersion 所标明的是 list 响应被构造时的资源版本。

`resourceVersion` 参数

GET、LIST 和 WATCH 操作都支持 resourceVersion 参数。

参数的具体含义取决于所执行的操作和所给的 resourceVersion 值：

对于 GET 和 LIST 而言，资源版本的语义为：

GET：

resourceVersion 未设置	resourceVersion=”0”	resourceVersion=”<非零值>”
最新版本	任何版本	不老于给定版本

LIST：

v1.19 及以上版本的 API 服务器支持 resourceVersionMatch 参数，用以确定如何对 LIST 调用应用 resourceVersion 值。强烈建议在为 LIST 调用设置了 resourceVersion 时也设置 resourceVersionMatch。如果 resourceVersion 未设置，则 resourceVersionMatch 是不允许设置的。为了向后兼容，客户端必须能够容忍服务器在某些场景下忽略 resourceVersionMatch 的行为：

当设置 resourceVersionMatch=NotOlderThan 且指定了 limit 时，客户端必须能够处理 HTTP 410 “Gone” 响应。例如，客户端可以使用更新一点的 resourceVersion 来重试，或者回退到 resourceVersion="" （即允许返回任何版本）。
当设置了 resourceVersionMatch=Exact 且未指定 limit 时，客户端必须验证响应数据中 ListMeta 的 resourceVersion 与所请求的 resourceVersion 匹配，并处理二者可能不匹配的情况。例如，客户端可以重试设置了 limit 的请求。

除非你对一致性有着非常强烈的需求，使用 resourceVersionMatch=NotOlderThan 同时为 resourceVersion 设定一个已知值是优选的交互方式，因为与不设置 resourceVersion 和 resourceVersionMatch 相比，这种配置可以取得更好的集群性能和可扩缩性。后者需要提供带票选能力的读操作。

resourceVersionMatch 参数	分页参数	resourceVersion 未设置	resourceVersion=”0”	resourceVersion=”<非零值>”
resourceVersionMatch 未设置	limit 未设置	最新版本	任意版本	不老于指定版本
resourceVersionMatch 未设置	limit=n, continue 未设置	最新版本	任意版本	精确匹配
resourceVersionMatch 未设置	limit=n, continue=<token>	Continue 令牌、精确匹配	非法请求，视为 Continue 令牌、精确匹配	非法请求，HTTP `400 Bad Request`
resourceVersionMatch=Exact	limit 未设置	非法请求	非法请求	精确匹配
resourceVersionMatch=Exact	limit=n, continue 未设置	非法请求	非法请求	精确匹配
resourceVersionMatch=NotOlderThan	limit 未设置	非法请求	任意版本	不老于指定版本
resourceVersionMatch=NotOlderThan	limit=n, continue 未设置	非法请求	任意版本	不老于指定版本

脚注：

* 如果服务器无法正确处理 resourceVersionMatch 参数，其行为与未设置该参数相同。

GET 和 LIST 操作的语义含义如下：

最新版本： 返回资源版本为最新的数据。所返回的数据必须一致（通过票选读操作从 etcd 中取出）。
任意版本： 返回任意资源版本的数据。优选最新可用的资源版本，不过不能保证强一致性；返回的数据可能是任何资源版本的。请求返回的数据有可能是客户端以前看到过的很老的资源版本。尤其在某些高可用配置环境中，网络分区或者高速缓存未被更新等状态都可能导致这种状况。不能容忍这种不一致性的客户端不应采用此语义。
不老于指定版本： 返回至少比所提供的 resourceVersion 还要新的数据。优选最新的可用数据，不过最终提供的可能是不老于所给 resourceVersion 的任何版本。对于发给能够正确处理 resourceVersionMatch 参数的服务器的 LIST 请求，此语义保证 ListMeta 中的 resourceVersion 不老于请求的 resourceVersion，不过不对列表条目之 ObjectMeta 的 resourceVersion 提供任何保证。这是因为 ObjectMeta.resourceVersion 所跟踪的是列表条目对象上次更新的时间，而不是对象被返回时是否是最新。
确定版本： 返回精确匹配所给资源版本的数据。如果所指定的 resourceVersion 的数据不可用，服务器会响应 HTTP 410 “Gone”。对于发送给能够正确处理 resourceVersionMatch 参数的服务器的 LIST 请求而言，此语义会保证 ListMeta 中的 resourceVersion 与所请求的 resourceVersion 匹配，不过不对列表条目之 ObjectMeta 的 resourceVersion 提供任何保证。这是因为 ObjectMeta.resourceVersion 所跟踪的是列表条目对象上次更新的时间，而不是对象被返回时是否是最新。
Continue 令牌、精确匹配： 返回原先带分页参数的 LIST 调用中指定的资源版本的数据。在最初的带分页参数的 LIST 调用之后，所有分页式的 LIST 调用都使用所返回的 Continue 令牌来跟踪最初提供的资源版本，

对于 WATCH 操作而言，资源版本的语义如下：

WATCH：

resourceVersion 未设置	resourceVersion=”0”	resourceVersion=”<非零值>”
读取状态并从最新版本开始	读取状态并从任意版本开始	从指定版本开始

WATCH 操作语义的含义如下：

读取状态并从最新版本开始： 从最新的资源版本开始 WATCH 操作。这里的最新版本必须是一致的（即通过票选读操作从 etcd 中取出）。为了建立初始状态， WATCH 首先会处理一组合成的 “Added” 事件，这些事件涵盖在初始资源版本中存在的所有资源实例。所有后续的 WATCH 事件都是关于 WATCH 开始时所处资源版本之后发生的变更。
读取状态并从任意版本开始： 警告：通过这种方式初始化的 WATCH 操作可能会返回任何状态的停滞数据。请在使用此语义之前执行复核，并在可能的情况下采用其他语义。此语义会从任意资源版本开始执行 WATCH 操作，优选最新的可用的资源版本，不过不是必须的；采用任何资源版本作为起始版本都是被允许的。 WATCH 操作有可能起始于客户端已经观测到的很老的版本。在高可用配置环境中，因为网络分裂或者高速缓存未及时更新的原因都会造成此现象。如果客户端不能容忍这种不一致性，就不要使用此语义来启动 WATCH 操作。为了建立初始状态，WATCH 首先会处理一组合成的 “Added” 事件，这些事件涵盖在初始资源版本中存在的所有资源实例。所有后续的 WATCH 事件都是关于 WATCH 开始时所处资源版本之后发生的变更。
从指定版本开始： 从某确切资源版本开始执行 WATCH 操作。WATCH 事件都是关于 WATCH 开始时所处资源版本之后发生的变更。与前面两种语义不同，WATCH 操作开始的时候不会生成或处理为所提供资源版本合成的 “Added” 事件。我们假定客户端既然能够提供确切资源版本，就应该已经拥有了起始资源版本对应的初始状态。

“410 Gone” 响应

服务器不需要提供所有老的资源版本，在客户端请求的是早于服务器端所保留版本的 resourceVersion 时，可以返回 HTTP 410 (Gone) 状态码。客户端必须能够容忍 410 (Gone) 响应。参阅高效检测变更以了解如何在监测资源时处理 410 (Gone) 响应。

如果所请求的 resourceVersion 超出了可应用的 limit，那么取决于请求是否是通过高速缓存来满足的，API 服务器可能会返回一个 410 Gone HTTP 响应。

不可用的资源版本

服务器不必未无法识别的资源版本提供服务。针对无法识别的资源版本的 LIST 和 GET 请求可能会短暂等待，以期资源版本可用。如果所给的资源版本在一定的时间段内仍未变得可用，服务器应该超时并返回 504 (Gateway Timeout)，且可在响应中添加 Retry-After 响应头部字段，标明客户端在再次尝试之前应该等待多少秒钟。目前，kube-apiserver 也能使用 Too large resource version（资源版本过高） 消息来标识这类响应。针对某无法识别的资源版本的 WATCH 操作可能会无限期（直到请求超时）地等待下去，直到资源版本可用。

Kubernetes API 概念

Kubernetes API 概念

标准 API 术语

高效检测变更

监视书签（Watch Bookmark）

分块检视大体量结果

以表格形式接收资源

资源的其他表示形式

Protobuf encoding

资源删除

单个资源 API

试运行

发起试运行请求

试运行的授权

生成的值

服务器端应用

介绍

字段管理

冲突

管理器

应用与更新

合并策略

定制资源

在控制器中使用服务器端应用机制

转移属主关系

在用户间移交属主角色

与客户端应用的比较

从客户端应用升级到服务器端应用

从服务器端应用降格为客户端应用

API 端点

清除 managedFields

禁用此功能特性

资源版本

metadata 中的 resourceVersion

resourceVersion 参数

“410 Gone” 响应

不可用的资源版本

清除 `managedFields`

`metadata` 中的 `resourceVersion`

`resourceVersion` 参数