Kubernetes 权威指南之 Kubernetes API 详解

编者按：InfoQ 开设栏目“品味书香”，精选技术书籍的精彩章节，以及分享看完书留下的思考和收获，欢迎大家关注。本文节选自龚正、吴治辉等编著《Kubernetes 权威指南》中的章节“Kubernetes API 详解”，介绍Kubernetes 的API。

Kubernetes API 概述

Kubernetes API 是集群系统中的重要组成部分，Kubernetes 中各种资源（对象）的数据通过该 API 接口被提交到后端的持久化存储（etcd）中，Kubernetes 集群中的各部件之间通过该 API 接口实现解耦合，同时 Kubernetes 集群中一个重要且便捷的管理工具 kubectl 也是通过访问该 API 接口实现其强大的管理功能的。Kubernetes API 中的资源对象都拥有通用的元数据，资源对象也可能存在嵌套现象，比如在一个 Pod 里面嵌套多个 Container。创建一个 API 对象是指通过 API 调用创建一条有意义的记录，该记录一旦被创建，Kubernetes 将确保对应的资源对象会被自动创建并托管维护。

在 Kubernetes 系统中，大多数情况下，API 定义和实现都符合标准的 HTTP REST 格式， 比如通过标准的 HTTP 动词（POST、PUT、GET、DELETE）来完成对相关资源对象的查询、创建、修改、删除等操作。但同时 Kubernetes 也为某些非标准的 REST 行为实现了附加的 API 接口，例如 Watch 某个资源的变化、进入容器执行某个操作等。另外，某些 API 接口可能违背严格的 REST 模式，因为接口不是返回单一的 JSON 对象，而是返回其他类型的数据，比如 JSON 对象流（Stream）或非结构化的文本日志数据等。

Kubernetes 开发人员认为，任何成功的系统都会经历一个不断成长和不断适应各种变更的过程。因此，他们期望 Kubernetes API 是不断变更和增长的。同时，他们在设计和开发时，有意识地兼容了已存在的客户需求。通常，新的 API 资源（Resource）和新的资源域不希望被频繁地加入系统。资源或域的删除需要一个严格的审核流程。

为了方便查阅 API 接口的详细定义，Kubernetes 使用了 swagger-ui 提供 API 在线查询功能，其官网为 http://kubernetes.io/third_party/swagger-ui/，Kubernetes 开发团队会定期更新、生成 UI 及文档。Swagger UI 是一款 REST API 文档在线自动生成和功能测试软件，关于 Swagger 的内容请访问官网 http://swagger.io。

运行在 Master 节点上的 API Server 进程同时提供了 swagger-ui 的访问地址：http://: /swagger-ui/。假设我们的 API Server 安装在 192.168.1.128 服务器上，绑定了 8080 端口，则可以通过访问 http://192.168.1.128:8080/swagger-ui/ 来查看 API 信息，如图 3.1 所示。

图 3.1 swagger-ui

单击 api/v1 可以查看所有 API 的列表，如图 3.2 所示。

图 3.2 查看 API 列表

以 create a Pod 为例，找到 Rest API 的访问路径为：/api/v1/namespaces/{namespace}/pods，如图 3.3 所示。

图 3.3 Create a Pod API

单击链接展开，即可查看详细的 API 接口说明，如图 3.4 所示。

图 3.4 Create a Pod API 详细说明

单击 Model 链接，则可以查看文本格式显示的 API 接口描述，如图 3.5 所示。

图 3.5 Create a Pod API 文本格式详细说明

我们看到，在 Kubernetes API 中，一个 API 的顶层（Top Level）元素由 kind、apiVersion、metadata、spec 和 status 等几个部分组成，接下来，我们分别对这几个部分进行说明。

kind 表明对象有以下三大类别。

（1）对象（objects）：代表在系统中的一个永久资源（实体），例如 Pod、RC、Service、Namespace 及 Node 等。通过操作这些资源的属性，客户端可以对该对象做创建、修改、删除和获取操作。

（2）列表（list）：一个或多个资源类别的集合。列表有一个通用元数据的有限集合。所有列表（lists）通过“items”域获得对象数组。例如 PodLists、ServiceLists、NodeLists。大部分定义在系统中的对象都有一个返回所有资源（resource）集合的端点，以及零到多个返回所有资源集合的子集的端点。某些对象有可能是单例对象（singletons），例如当前用户、系统默认用户等，这些对象没有列表。

（3）简单类别（simple）：该类别包含作用在对象上的特殊行为和非持久实体。该类别限制了使用范围，它有一个通用元数据的有限集合，例如 Binding、 Status。

apiVersion 表明 API 的版本号，当前版本默认只支持 v1。

Metadata 是资源对象的元数据定义，是集合类的元素类型，包含一组由不同名称定义的属性。在 Kubernetes 中每个资源对象都必须包含以下 3 种 Metadata。

（1）namespace：对象所属的命名空间，如果不指定，系统则会将对象置于名为“default”的系统命名空间中。

（2）name：对象的名字，在一个命名空间中名字应具备唯一性。

（3）uid：系统为每个对象生成的唯一 ID，符合 RFC 4122 规范的定义。

此外，每种对象还应该包含以下几个重要元数据。

（1）labels：用户可定义的“标签”，键和值都为字符串的 map，是对象进行组织和分类的一种手段，通常用于标签选择器（Label Selector），用来匹配目标对象。

（2）annotations：用户可定义的“注解”，键和值都为字符串的 map，被 Kubernetes 内部进程或者某些外部工具使用，用于存储和获取关于该对象的特定元数据。

（3）resourceVersion：用于识别该资源内部版本号的字符串，在用于 Watch 操作时，可以避免在 GET 操作和下一次 Watch 操作之间造成的信息不一致，客户端可以用它来判断资源是否改变。该值应该被客户端看作不透明，且不做任何修改就返回给服务端。客户端不应该假定版本信息具有跨命名空间、跨不同资源类别、跨不同服务器的含义。

（4）creationTimestamp：系统记录创建对象时的时间戳，符合 RFC 3339 规范。

（5）deletionTimestamp：系统记录删除对象时的时间戳，符合 RFC 3339 规范。

（6）selfLink：通过 API 访问资源自身的 URL，例如一个 Pod 的 link 可能是 /api/v1/namespaces/ default/pods/frontend-o8bg4。

spec 是集合类的元素类型，用户对需要管理的对象进行详细描述的主体部分都在 spec 里给出，它会被 Kubernetes 持久化到 etcd 中保存，系统通过 spec 的描述来创建或更新对象，以达到用户期望的对象运行状态。spec 的内容既包括用户提供的配置设置、默认值、属性的初始化值，也包括在对象创建过程中由其他相关组件（例如 schedulers、auto-scalers）创建或修改的对象属性，比如 Pod 的 Service IP 地址。如果 spec 被删除，那么该对象将会从系统中被删除。

Status 用于记录对象在系统中的当前状态信息，它也是集合类元素类型，status 在一个自动处理的进程中被持久化，可以在流转的过程中生成。如果观察到一个资源丢失了它的状态（Status），则该丢失的状态可能被重新构造。以 Pod 为例，Pod 的 status 信息主要包括 conditions、containerStatuses、hostIP、phase、podIP、startTime 等。其中比较重要的两个状态属性如下。

（1）phase：描述对象所处的生命周期阶段，phase 的典型值是“Pending”（创建中）“Running”“Active”（正在运行中）或“Terminated”（已终结），这几种状态对于不同的对象可能有轻微的差别，此外，关于当前 phase 附加的详细说明可能包含在其他域中。

（2）condition：表示条件，由条件类型和状态值组成，目前仅有一种条件类型 Ready，对应的状态值可以为 True、False 或 Unknown。一个对象可以具备多种 condition，而 condition 的状态值也可能不断发生变化，condition 可能附带一些信息，例如最后的探测时间或最后的转变时间。

API 版本

为了在兼容旧版本的同时不断升级新的 API，Kubernetes 提供了多版本 API 的支持能力，每个版本的 API 通过一个版本号路径前缀进行区分，例如 /api/v1beta3。通常情况下，新旧几个不同的 API 版本都能涵盖所有的 Kubernetes 资源对象，在不同的版本之间这些 API 接口存在一些细微差别。Kubernetes 开发团队基于 API 级别选择版本而不是基于资源和域级别，是为了确保 API 能够描述一个清晰的连续的系统资源和行为的视图，能够控制访问的整个过程和控制实验性 API 的访问。

API 及版本发布建议描述了版本升级的当前思路。版本 v1beta1、v1beta2 和 v1beta3 为不建议使用（Deprecated）的版本，请尽快转到 v1 版本。在 2015 年 6 月 4 日，Kubernetes v1 版本 API 正式发布。版本 v1beta1 和 v1beta2 API 在 2015 年 6 月 1 日被删除，版本 v1beta3 API 在 2015 年 7 月 6 日被删除。

API 详细说明

API 资源使用 REST 模式，具体说明如下。

（1）GET /< 资源名的复数格式 >：获得某一类型的资源列表，例如 GET /pods 返回一个 Pod 资源列表。

（2）POST /< 资源名的复数格式 >：创建一个资源，该资源来自用户提供的 JSON 对象。

（3）GET /< 资源名复数格式 >/< 名字 >：通过给出的名称（Name）获得单个资源，例如 GET /pods/first 返回一个名称为“first”的 Pod。

（4）DELETE /< 资源名复数格式 >/< 名字 >：通过给出的名字删除单个资源，删除选项（DeleteOptions）中可以指定的优雅删除（Grace Deletion）的时间（GracePeriodSeconds），该可选项表明了从服务端接收到删除请求到资源被删除的时间间隔（单位为秒）。不同的类别（Kind）可能为优雅删除时间（Grace Period）申明默认值。用户提交的优雅删除时间将覆盖该默认值，包括值为 0 的优雅删除时间。

（5）PUT /< 资源名复数格式 >/< 名字 >：通过给出的资源名和客户端提供的 JSON 对象来更新或创建资源。

（6）PATCH /< 资源名复数格式 >/< 名字 >：选择修改资源详细指定的域。

对于 PATCH 操作，目前 Kubernetes API 通过相应的 HTTP 首部“Content-Type”对其进行识别。

目前支持以下三种类型的 PATCH 操作。

（1）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。

（2）Merge Patch, Content-Type: application/merge-json-patch+json。在 RFC7386 的定义中，Merge Patch 必须包含对一个资源对象的部分描述，这个资源对象的部分描述就是一个 JSON 对象。该 JSON 对象被提交到服务端，并和服务端的当前对象合并，从而创建一个新的对象。详情请查看 RFC73862 说明，网址为 HTTPs://tools.ietf.org/html/rfc7386。

（3）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 请求的代理。

API 响应说明

API Server 响应用户请求时附带一个状态码，该状态码符合 HTTP 规范。表 3.1 列出了 API Server 可能返回的状态码。

表 3.1 API Server 可能返回的状态码

状态码

编码

描述

200

OK

表明请求完全成功

201

Created

表明创建类的请求完全成功

204

NoContent

表明请求完全成功，同时 HTTP 响应不包含响应体。

在响应 OPTIONS 方法的 HTTP 请求时返回

307

TemporaryRedirect

表明请求资源的地址被改变，建议客户端使用 Location 首部给出的临时 URL 来定位资源

400

BadRequest

表明请求是非法的，建议客户不要重试，修改该请求

401

Unauthorized

表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为客户端必须提供认证信息。如果客户端提供了认证信息，则返回该状态码，表明服务端指出所提供的认证信息不合适或非法

403

Forbidden

表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为该请求被设置成拒绝访问。建议客户不要重试，修改该请求

404

NotFound

表明所请求的资源不存在。建议客户不要重试，修改该请求

405

MethodNotAllowed

表明请求中带有该资源不支持的方法。建议客户不要重试，修改该请求

409

Conflict

表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成

422

UnprocessableEntity

表明由于所提供的作为请求部分的数据非法，创建或修改操作不能被完成

429

TooManyRequests

表明超出了客户端访问频率的限制或者服务端接收到多于它能处理的请求。建议客户端读取相应的 Retry-After 首部，然后等待该首部指出的时间后再重试

500

InternalServerError

表明服务端能被请求访问到，但是不能理解用户的请求；或者服务端内产生非预期中的一个错误，而且该错误无法被认知；或者服务端不能在一个合理的时间内完成处理（这可能由于服务器临时负载过重造成或者由于和其他服务器通信时的一个临时通信故障造成）

503

ServiceUnavailable

表明被请求的服务无效。建议客户不要重试，修改该请求

504

ServerTimeout

表明请求在给定的时间内无法完成。客户端仅在为请求指定超时（Timeout）参数时会得到该响应

在调用 API 接口发生错误时，Kubernetes 将会返回一个状态类别（Status Kind）。下面是两种常见的错误场景：

（1）当一个操作不成功时（例如，当服务端返回一个非 2xx HTTP 状态码时）；

（2）当一个 HTTP DELETE 方法调用失败时。

状态对象被编码成 JSON 格式，同时该 JSON 对象被作为请求的响应体。该状态对象包含人和机器使用的域，这些域中包含来自 API 的关于失败原因的详细信息。状态对象中的信息补充了对 HTTP 状态码的说明。 例如：

$ curl -v -k -H ＂Authorization: Bearer WhCDvq4VPpYhrcfmF6ei7V9qlbqTubUc＂ HTTPs://10.240.122.184:443/api/v1/namespaces/default/pods/grafana
 
> GET /api/v1/namespaces/default/pods/grafana HTTP/1.1
 
> User-Agent: curl/7.26.0
 
> Host: 10.240.122.184
 
> Accept: */*
 
> Authorization: Bearer WhCDvq4VPpYhrcfmF6ei7V9qlbqTubUc
 
>
 
 
 
< HTTP/1.1 404 Not Found
 
< Content-Type: application/json
 
< Date: Wed, 20 May 2015 18:10:42 GMT
 
< Content-Length: 232
 
<
 
{
 
  ＂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”域包含说明该操作失败原因的可读描述。如果该域的值为空，则表示该域内没有任何说明信息。“reason”域澄清 HTTP 状态码，但没有覆盖该状态码。

“details”可能包含和“reason”域相关的扩展数据。每个“reason”域可以定义它的扩展的“details”域。该域是可选的，返回数据的格式是不确定的，不同的 reason 类型返回的“details”域的内容不一样。

书籍介绍

Kubernetes 是由谷歌开源的 Docker 容器集群管理系统，为容器化的应用提供了资源调度、部署运行、服务发现、扩容、缩容等一整套功能。本书从 一个开发者的角度去理解、分析和解决问题，囊括了 Kubernetes 入门、核心原理、实战开发、运维、高级案例及源码分析等方面的内容，图文并茂、内容 丰富、由浅入深、讲解全面；并围绕着生产环境中可能出现的问题，给出了大量的典型案例，比如安全问题、网络方案的选择、高可用性方案及 Trouble Shooting 技巧等，有很好的可借鉴性。