Kubernetes API 使用文档

原文地址

API 概述

※ 资源分类

这是对 Kubernetes API 及其主要功能提供的基本资源类型的高级概述。

Workloads：用于在集群中管理和运行容器；
Discovery & LB：用于将 Workloads “缝合” 到一个可从外部访问的负载均衡的服务中；
Config & Storage：用于将初始化数据注入到应用程序中，并保留容器外部的数据；
Cluster：用于定义如何配置集群，这些通常仅由集群运营商使用；
Metadata：用于配置群集内其他资源的行为，例如用于扩展 Workloads 的 HorizontalPodAutoscaler

※ 资源对象

资源对象通常包含 3 个组件：

ResourceSpec：这由用户定义并描述系统所期望的状态，在创建或更新对象时填写；
ResourceStatus：这由服务器填写并报告系统的当前状态，只有 Kubernetes 组件才能填写此内容；
Resource ObjectMeta：这是关于资源的元数据，例如 name / type / api version / annotations / labels，包含可能由后端用户和系统更新的字段（如 annotations）

※ 资源操作

大部分资源提供如下操作：

▶ Create

Create 操作会在存储后端创建资源。资源创建后，系统将应用所期望的状态。

▶ Update

更新有 2 种形式：Replace 和 Patch

Replace：替换资源对象将通过提供的 spec 替换现有的 spec 来更新资源。对于读写操作，这是安全的，因为如果资源在读和写之间被修改，则会发生乐观锁定失败。注意：ResourceStatus 将被系统忽略，并且不会被更新，要更新状态，必须调用特定的状态更新操作。

注意：替换资源对象可能不会立即传播到下游对象。例如，替换 ConfigMap 或 Secret 资源不会导致所有 Pod 看到更改，除非 Pod 在带外重新启动。

Patch：Patch 会更改特定字段，如何合并更改是每个字段定义的。列表可以被替换或合并，合并列表不会保留排序。

Patch 操作永远不会导致乐观锁定失败，并且最后一次写入会获胜。如果在更新之前未读取完整状态，或者乐观锁定失败不可取，则建议使用 patch 操作。修补复杂 types、arrays 和 maps 时，如何应用修补程序是以每个字段为基础定义的，并可以替换字段的当前值，也可以将内容合并到当前值中。

▶ Read

读取有 3 种方式：Get 、 List 和 Watch

Get：按名称检索特定的资源对象；

List：检索命名空间内特定类型的所有资源对象，并且结果可以限制为与选择器查询结果匹配的资源；

List All Namespaces：像 List 一样，但是跨所有命名空间检索资源；

Watch：Watch 将在对象更新时汇出结果，类似于回调，watch 用于响应资源的更改。

▶ Delete

Delete 将删除资源。根据特定的资源，子对象可能会或可能不会被服务器当做垃圾收集，详情请参阅特定资源对象的注释。

▶ 额外操作

资源可以定义特定于该资源类型的附加操作。

Rollback：将 PodTemplate 回滚到以前的版本，仅适用于某些资源类型；

Read / Write Scale：读取或更新给定资源的副本数量，仅适用于某些资源类型；

Read / Write Status：读取或更新资源对象的状态，状态只能通过这些更新操作进行更改。

WORKLOADS

Workloads 资源负责管理和运行集群上的容器。容器（Containers）由控制器（Controllers）通过 Pod 创建，Pods 运行容器并提供环境依赖，如注入到容器中的共享或永久存储卷、配置或加密数据。

最常见的控制器是：

Deployments 无状态持久应用（如 http servers）
StatefulSets 有状态持久应用（如 database）
Jobs 运行至完成的应用（如 batch jobs）

DISCOVERY & LOAD BALANCING

Discovery and Load Balancing 负责将 Workloads “缝合” 到一个可从外部访问的负载均衡的服务中。默认情况下，Workloads 只能在群集内访问，它们必须通过 LoadBalancer 或 NodePort Service 暴露到外部。对于开发，可以使用 kubectl proxy命令通过代理 api 主机访问内部可访问的 Workloads 。

常用的资源类型：

Services 提供跨多个 Workload 副本的负载均衡的单个 IP 端点。
Ingress 提供路由到一个或多个服务的 https(s) 端点

CONFIG & STORAGE

Config and Storage 资源负责将数据注入到应用程序中，并保留容器外部的数据。

常用的资源类型：

ConfigMaps 通过环境变量、命令行参数或文件提供注入应用的 K-V 键值对
Secrets 通过文件提供注入应用的二进制数据
Volumes 提供容器外部的文件系统。可能在同一个 Pod 中跨 Container 容器共享，并且其寿命持续超出 Container 或 Pod。

METADATA

Metadata resources 负责集群内其他资源的行为。

常用的资源类型：

HorizontalPodAutoscaler 自动缩放 workloads 的副本数量以响应加载
PodDisruptionBudget 在执行维护时，可以配置给定 workloads 中的多少副本可能同时不可用
ThirdPartyResource 使用自己的类型扩展 Kubernetes API
Event 群集中资源生命周期事件的通知

API 调用方式

▶ kubectl

示例：创建 Deployment

1.  `$ echo 'apiVersion: apps/v1`

2.  `kind: Deployment`

3.  `metadata:`

4.  `name: deployment-example`

5.  `spec:`

6.  `replicas: 3`

7.  `revisionHistoryLimit: 10`

8.  `template:`

9.  `metadata:`

10.  `labels:`

11.  `app: nginx`

12.  `spec:`

13.  `containers:`

14.  `- name: nginx`

15.  `image: nginx:1.10`

16.  `ports:`

17.  `- containerPort: 80`

18.  `' | kubectl create -f -`

yaml 文件编写的规则拆解如下图：

其他资源的创建或其他操作，都可以按照这种方式来操作。

▶ curl

需要使用 kubectl proxy


1.  `$ kubectl proxy`

2.  `$ curl -X POST -H 'Content-Type: application/yaml' --data '`

3.  `apiVersion: apps/v1beta1`

4.  `kind: Deployment`

5.  `metadata:`

6.  `name: deployment-example`

7.  `spec:`

8.  `replicas: 3`

9.  `revisionHistoryLimit: 10`

10.  `template:`

11.  `metadata:`

12.  `labels:`

13.  `app: nginx`

14.  `spec:`

15.  `containers:`

16.  `- name: nginx`

17.  `image: nginx:1.10`

18.  `ports:`

19.  `- containerPort: 80`

20.  `' http://127.0.0.1:8001/apis/apps/v1/namespaces/default/deployments`

推荐：译：基于注解的控制器：Spring Web/WebFlux 和测试

上一篇：Spring-5-webflux 和阻塞与非阻塞 JDBC