Kubernetes API概述

原创
半兽人 发表于: 2018-11-30   最后更新时间: 2018-11-30 22:15:17  
{{totalSubscript}} 订阅, 5,421 游览

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)和新的资源域不希望被频繁地加入系统。资源或域的删除需要一个严格的审核流程。

Kubernetes API文档官网为:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/

运行在Master节点上的API Server进程同时提供了Swagger格式的API网页。Swagger UI是一款REST API文档在线自动生成和功能测试软件,假设我们的API Server安装在172.16.10.100服务器上,绑定了6443端口,则可以通过访问https://172.16.10.100:6443/swagger-ui/来查看API信息,如图所示。

screenshot

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

screenshot

以创建一个Pod为例,找到Rest API的访问路径为:/api/v1/namespaces/{namespace}/pods,单击Model链接,则可以查看文本格式显示的API接口描述。

screenshot

单击链接展开,即可查看详细的API接口说明,如图所示。
screenshot
单击Model链接,则可以查看文本格式显示的API接口描述,如图所示。

screenshot

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

更新于 2018-11-30

凡夫俗子 4年前

api Server默认是需要认证的,Swagger UI通过浏览器匿名用户是不允许访问的,怎么解决?

查看kubernetes更多相关的文章或提一个关于kubernetes的问题,也可以与我们一起分享文章