[第一章]Kubernetes API介绍

• 1: Kubernetes 平台一览
• 2: openapi规范
• 3: Group-Version-Resource
• 4: Verbs 和 Kinds
• 5: 子资源
• 6: 官方API参考文档

1 - Kubernetes 平台一览

在链条的一侧，用户声明高级资源来构建要部署的应用程序： Deployments，Ingresses，等等。

在中间，controller 被激活，将这些资源转化为低级别的资源（Pod），调度器将这些资源分配到节点。在链条的另一端，节点代理将低级别的资源部署到节点上。

Kubernetes 平台的主要元素（通常称为控制平面）在图1-1中突出显示，并在下文中描述：

1. API server: 这是控制平面上的中心点；用户和控制平面的各个部分联系这个API来创建、获取、删除、更新和观察资源。

2. etcd数据库: 只能由API服务器访问，用于保存与资源有关的数据。

3. Controller manager: 运行 Controller，将用户声明的高级资源转化为部署在节点上的低级别资源。控制器连接到API服务器，观察高层资源，创建、删除和更新低层资源，以满足高层资源中声明的规格。

4. Scheduler: 将低级资源分配到各个节点上。调度器连接到API服务器，观察未受影响的资源并将其连接到节点上。

5. Kubelet: 这是一个运行在集群所有节点上的代理，每个代理都管理着影响到其节点的工作负载。kubelet 连接到 API 服务器，观察影响到其节点的Pods资源，并使用本地容器运行时部署相关容器。

6. Kube proxy: 这是一个在集群的所有节点上运行的代理，每个代理都管理着影响其节点的网络配置。Kube proxy 连接到API服务器，观察服务资源并在其节点上配置相关的网络规则。

2 - openapi规范

Kubernetes 的API 是HTTP REST API。Kubernetes 团队提供了 OpenAPI 格式的API规范，V2格式的规范在 https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec，Kubernetes v1.24 v3 格式的规范在 https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/v3。

这些规范也可以从 API 服务器的这些路径访问： /openapi/v2 和 /openapi/v3 。

OpenAPI规范是由不同部分组成的，其中有路径列表和定义列表。路径是你用来请求这个API的URL，对于每个路径，规范给出了不同的操作，如 get、delte 或 post 。然后，对于每个操作，规范指出了什么是请求的参数和主体格式，以及什么是可能的响应代码和相关的响应主体格式。

请求和响应的参数和主体可以是简单的类型，也可以是更普遍的包含数据的结构。定义列表包括帮助建立操作的请求和响应的参数和主体的数据结构。

图1-2是一个 User API 规范的简化视图。这个API可以接受两个不同的路径： /user/{userId} 和 /user。第一个路径，/user/{userId}，可以接受两个操作，分别是 get 和 delete，用来接收特定用户的信息，给出其用户ID；以及删除特定用户的信息，给出其用户ID。第二个路径，/user，可以接受一个单一的操作，post，以添加一个新的用户，给定其信息。

在这个API中，给出了一个 User 结构体的定义，描述了一个用户的信息：其ID、first name 和 last name。这个数据结构被用于第一条路径上的 get 操作的响应体中，以及第二条路径上的 post 操作的请求体中。

3 - Group-Version-Resource

Kubernetes API 是 REST API，因此它管理资源和资源的路径，这些资源遵循REST的命名惯例–即使用复数名称来识别资源，并将这些资源分组。

因为 Kubernetes API 管理着数以百计的资源，所以它们被分组，而且因为 API 的发展，这些资源是有版本的。由于这些原因，每个资源都属于一个给定的 group和 version，每个资源都由 Group-Version-Resource 唯一标识，通常称为 GVR。

要找到 Kubernetes API 中的各种资源，你可以浏览 OpenAPI 规范，提取不同的路径。传统的资源（如pod或节点）将在 Kubernetes API 的早期引入，都属于组 core 和版本v1。

管理整个集群的遗留资源的路径遵循 /api/v1/<plural_resource_name> 的格式–例如，/api/v1/nodes 来管理节点。请注意，core group 在路径中不被代表。要管理特定命名空间中的资源，路径格式是 /api/v1/namespaces/<namespace_name>/<plural_resource_name> –例如，/api/v1/namespaces/default/pods 用于管理默认命名空间中的pod。

较新的资源可以通过格式为 /apis/<group>/<version>/<plural_resource_name>或 /apis/<group>/<version>/namespaces/<namespace_name>/<plural_resource_name> 的路径访问。

概括地说，获取资源的各种路径的格式是：

• /api/v1/<plural_name> - 访问传统的非命名空间的资源。例如：/api/v1/nodes，访问无命名空间的节点资源。或

• 访问整个集群的传统命名方式的资源，例如：/api/v1/pods，访问所有命名空间的pod。

• /api/v1/namespaces/<ns>/<plural_name> - 访问特定命名空间中的遗留带命名空间的资源。例如：/api/v1/namespaces/default/pods，访问默认命名空间中的pod。

• /apis/<group>/<version>/<plural_name> - 访问特定组和版本中的非命名空间资源。例如：/apis/storage.k8s.io/v1/storageclasses来访问非命名空间的storageclasses（组storage.k8s.io，版本v1）。或

• 访问整个集群的命名空间资源。例如：/apis/apps/v1/deployments，访问所有命名空间的 deployment。

• /apis/<group>/<version>/namespaces/<ns>/<plural_name> - 访问特定命名空间的命名资源。例如：/apis/apps/v1/namespaces/default/deployments访问默认命名空间中的deployment（分组为 apps，版本为 v1）。

4 - Verbs 和 Kinds

Kubernetes API为该规范添加了两个概念：Kubernetes API Verbs （动词）和Kubernetes Kinds。

Kubernetes API Verbs 被直接映射到 OpenAPI 规范中的操作。定义的 Verbs 动词是 get、create、update、patch、delete、list、watch 和d eletecollection。与HTTP动词的对应关系可以在表1-1中找到。

表1-1 Kubernetes API动词和HTTP动词的对应关系

Kubernetes API Verb	HTTP Verb
get	GET
create	POST
update	PUT
patch	PATCH
delete	DELETE
list	GET
watch	GET
deletecollection	DELETE

Kubernetes Kinds 是 OpenAPI 规范中定义的一个子集。当向 Kubernetes API 发出请求时，数据结构会通过请求和响应的主体进行交换。这些结构共享共同的字段，apiVersion 和 kind，以帮助请求的参与者识别这些结构。

如果你想让你的 User API 管理这个 Kind 概念，User 结构体将包含两个额外的字段，apiVersion 和 kind –例如，其值为 v1 和 User。要确定 Kubernetes OpenAPI 规范中的定义是否是 Kubernetes Kind，你可以查看定义的 x-kubernetes-group-version-kind 字段。如果这个字段被定义了，那么该定义就是一个 kind，它给你提供了apiVersion 和 kind 字段的值。

5 - 子资源

按照REST API的惯例，资源可以有子资源。子资源是属于另一个资源的，可以通过在资源名称后面指定其名称来访问，如下所示：

• /api/v1/<plural>/<res-name>/<sub-resource>

  例如: /api/v1/nodes/node1/status

• /api/v1/namespaces/<ns>/<plural>/<res-name>/<sub-resource>

  例如: /api/v1/namespaces/ns1/pods/pod1/status

• /apis/<group>/<version>/<plural>/<res-name>/<sub-resource>

  例如: /apis/storage.k8s.io/v1/volumeattachments/volatt1/status

• /apis/<grp>/<v>/namespaces/<ns>/<plural>/<name>/<sub-res>

  例如: /apis/apps/v1/namespaces/ns1/deployments/dep1/status

大多数 Kubernetes 资源都有一个 status 子资源。你可以看到，在编写 operator 时，operator 需要更新 status 子资源，以便能够表明 operator 观察到的这个资源的状态。在status 子资源中可以执行的操作有：get、patch 和 update。Pod有更多的子资源，包括 attach, binding, eviction, exec, log, portforward, 和 proxy。这些子资源对于获取特定的正在运行的 pod 的信息，或者在正在运行的 pod 上执行一些特定的操作，等等都很有用。

可以缩放的资源（即 deployment 、replicaset 等）有一个 scale 子资源。可以在 scale 子资源中执行的操作是 get、patch和update。

6 - 官方API参考文档

该API的官方参考文档在 https://kubernetes.io/docs/reference/kubernetes-api/。API管理的资源首先按类别（即工作负载、存储等）分组，对于每个类别，你可以获得一个带有简短描述的资源名称列表（图1-3）。

注意，这些类别并不是 Kubernetes API 定义的一部分，而是在本网站中用来帮助没有经验的用户在众多的可用资源中找到自己的方向。

准确地说，显示的名称不是REST意义上的资源名称，而是相关的主体种类，如图1-4所示。例如，在管理Pod时，REST路径中使用的资源名称是pods（即小写和复数），而在HTTP请求中用于交换Pod信息的定义被命名为Pod（即大写和单数）。请注意，其他种类可以与同一资源相关联。在本章的例子中，PodList种类（用于交换关于Pod列表的信息）也存在。

Deployment 文档

让我们来探讨一下这个地址提供的 Deployment 的参考文档：https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/。该页的标题 “Deployment” 是与图1-5所示的 Deployment 资源有关的主要种类。

头中指出的 apiVersion 可以帮助您为部署资源编写 YAML 清单，因为您需要为 Kubernetes 清单中的每个资源指定 apiVersion 和 kind。

在这种情况下，您知道部署的清单将以下列内容开始：

apiVersion: apps/v1
kind: Deployment

下一个 header 指出了编写Go代码时要使用的 import 。在第三章中，你将看到在Go中描述资源时如何使用这个导入。

在 header 之后，描述了一个结构体定义的列表，也可以从图1-6中的 Deployment 文档页的目录中获取。第一个是资源的主要种类（kind），后面可以选择用于第一种领域的结构体定义。

例如，Deployment kind 包含一个 spec 字段，类型为 DeploymentSpec，这将在后面描述。请注意，DeploymentSpec 不是在HTTP请求期间直接交换的结构体，因此，它不是一个 kind ，也不包含 kind 或 apiVersion 字段。

在主要 kind 及其相关定义之后，将显示与该资源相关的其他 kind。在本例中，是 DeploymentList kind。

操作文档

资源的API文档的下一个主题是对该资源或其子资源可能进行的操作列表，也可以从目录页中访问（见图1-6）。如图1-7所示，通过检查创建部署的操作细节，你可以看到要使用的HTTP请求动词和路径、请求过程中要传递的参数，以及可能的响应。请求使用的HTTP动词是POST，路径是 /apis/apps/v1/namespaces/{namespace}/deployments。

路径的 {namespace} 部分表示一个路径参数，它将被你想在其上创建部署的命名空间的名称所取代。你可以指定查询参数：dryRun、fieldManager、fieldValidation 和 pretty。这些参数将遵循格式为 path?dryRun=All 的路径。

请求的主体必须是一个Deployment 的种类。当使用 kubectl 时，你正在编写包含这个主体的 Kubernetes Manifest。在第三章中，你将看到如何在Go中构建主体。响应的HTTP代码可能是： 200、201、202和401；对于2xx代码，响应体将包含一个 Deployment 类型。

pod文档

有些结构体包含许多字段。对于它们，Kubernetes API 文档对字段进行了分类。一个例子是Pod资源的文档。

Pod 资源的文档页面首先包含主要种类 Pod 的描述，然后是 PodSpec 结构体的描述。PodSpec 结构体包含约40个字段。为了帮助你理解这些字段之间的关系，并简化它们的探索，它们被安排成不同的分类（categories）。PodSpec 字段的分类如下： Containers, Volumes, Scheduling, Lifecycle，等等。

此外，对于包含嵌套字段的字段，它们的描述一般是 inline 显示，以避免在结构体描述之间来回穿梭。然而，对于复杂的结构体，描述会随后在页面上报告，并且在字段名旁边有一个链接，以便能够方便地访问它。

对于 Spec 和 Status 结构来说，这种情况一直存在，因为它们在几乎所有的资源中都非常常见。此外，Pod中使用的一些结构体也是如此–例如，Container、EphemeralContainer、LifecycleHandler、NodeAffinity等等。

一些在多个资源中使用的结构被放置在通用定义部分，在字段名旁边有一个链接，可以很容易地访问它。在图1-8中，你可以看到 PodSpec 结构描述里面的容器类别。

你还可以看到，containers 和 initContainers 这些字段的类型与Container相同，Container在本页后面有描述，可以通过链接访问。imagePullSecrets字段的类型是 LocalObjectReference，这在通用定义部分有描述，也可以通过链接访问。

单页版的文档

另一个版本的API参考文档存在，并在一个页面上呈现。这个版本涵盖了一个Kubernretes版本所服务的所有资源版本（不仅仅是最新的版本）。这个版本（如果你想，改变路径的最后部分，以导航到另一个Kubernetes版本）可以在以下网址找到：

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/

总结

在本章中，你已经能够发现Kubernetes平台的架构，以及API server 发挥的核心作用。Kubernetes API 是一个HTTP REST API，资源被分类为各种有版本的分组。

类型 kind 是用于在API服务器和客户端之间交换数据的特定结构。你可以使用 Kubernetes 官方网站，以人类可读的形式浏览API规范，发现各种资源和种类的结构，每个资源和子资源的不同操作，以及它们相关的动词。