Kubernetes API概述

2020-08-15 0 By admin

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

一、Kubernetes API 资源对象和 REST 模式

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

二、Kubernetes 开发过程的思路和辅助工具

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

Kubernetes API文档官网为https://kubernetes.io/docs/reference,可以 通过相关链接查看不同版本的API文档,例如Kubernetes 1.14版本的链接为https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14。

2.1、Kubernetes 1.13 版本之前的 Swagger 页面

在Kubernetes 1.13版本及之前的版本中,Master的API Server服务提供了Swagger格式的API网页。
Swagger UI是一款REST API文档在线自动生成和功能测试软件,关于Swagger的内容请访问官网 http://swagger.io。我们通过设置kube-apiserver服务的启动参数–enable- swagger-ui=true来启用Swagger UI页面,其访问地址为http://master-ip:master-port/swagger-ui/。
假设API Server启动了192.168.18.3服务器上 的8080端口,则可以通过访问http://192.168.18.3:8080/swagger-ui/来查看 API列表。

三、Kubernetes API 中的顶层元素

在Kubernetes API中,一个API的顶层(Top Level)元素由kind、apiVersion、metadata、spec和status这5部分组成。

3.1、kind 对象的类型

kind表明对象有以下三大类别。
(1)对象(objects):代表系统中的一个永久资源(实体),例如Pod、RC、Service、Namespace及Node等。通过操作这些资源的属性,客户端可以对该对象进行创建、修改、删除和获取操作。
(2)列表(list):一个或多个资源类别的集合。所有列表都通过 items域获得对象数组,例如PodLists、ServiceLists、NodeLists。大部分被定义在系统中的对象都有一个返回所有资源集合的端点,以及零到多个返回所有资源集合的子集的端点。某些对象有可能是单例对象
(singletons),例如当前用户、系统默认用户等,这些对象没有列表。
(3)简单类别(simple):该类别包含作用在对象上的特殊行为和非持久实体。该类别限制了使用范围,它有一个通用元数据的有限集合,例如Binding、Status。

3.2、apiVersion表明API的版本号

当前版本默认只支持v1。

3.3、Metadata 资源对象的元数据定义

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

  1. namespace:对象所属的命名空间,如果不指定,系统则会将对象置于名为default的系统命名空间中。
  2. name:对象的名称,在一个命名空间中名称应具备唯一性。
  3. uid:系统为每个对象都生成的唯一ID,符合RFC 4122规范的定义。

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

  1. labels:用户可定义的“标签”,键和值都为字符串的map,是对象进行组织和分类的一种手段,通常用于标签选择器,用来匹配目标对象。
  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”。

3.4、spec 集合类的元素类型

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

3.5、Status 资源对象的状态

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可能附带一些信息,例如最后的探测时间或最后的转变时间。

四、OpenAPI 的格式访问

Kubernetes从1.14版本开始,使用 OpenAPI(https://www.openapis.org)的格式对API进行查询。其访问地址为http://master-ip:master-port/openapi/v2。
例如,使用命令行工 具curl进行查询:
curl http://192.168.18.3:8080/openapi/v2 | jq