引言

kubernetes API官方文档

对象的表示方法与设计理念

采用声明式API设计简述（DAP）

DAP是Mars-java 最近提出的一个新的开发方式，全称 Declarative API Programming， 提倡后端为一个独立的整体，不应该是为前端服务的，所以当前端需要接口的时候，只需要声明一个API给他，而不需要专门开发一个Controller出来
传统的后端接口开发流程

这样造成的后果就是控制层跟前段耦合性忒别高，并且实际情况下我们更关注的是service业务逻辑，所以就出现了声明式API.
声明式API开发流程

通过更换MarsReference的配置，可以关联到不同的业务逻辑
如果前端不需要这个接口了，直接无脑删就好了，因为这只是一个抽象方法，还原成本几乎为0
后端专注业务逻辑就好了，不需要考虑跟前端互动，前端需要的时候开个门就好了

Kubernetes 中API设计简述

在 Kubernetes 项目中，一个 API 对象在 Etcd 里的完整资源路径，是由：Group（API 组）、Version（API 版本）和 Resource（API 资源类型）三个部分组成的。通过这样的结构，整个 Kubernetes 里的所有 API 对象，实际上就可以用如下的树形结构表示出来：

要声明要创建一个 CronJob 对象，那么 YAML 文件的开始部分会这么写：

apiVersion: batch/v2alpha1
kind: CronJob
...

在这个 YAML 文件中，“CronJob”就是这个 API 对象的资源类型（Resource），“batch”就是它的组（Group），v2alpha1 就是它的版本（Version）。

版本控制（apiVersion）

为什么版本控制？

回答这个问题之前，首先得清楚一件事，那就是什么是版本控制？做APP后端开发的应该会很清楚，因为在给APP提供接口的时候，由于安装在用户手机上的 App 存在多个客户端版本的问题，这些版本大部分时候需要进行共存，但是Android 和 IOS 基本上都不允许App内置升级功能，用户又不愿意或拒绝升级，很多时候业务需求在不停的变化，就免不了对接口进行调整控制，此时就需要使用不同版本的Api接口进行控制。

实现版本控制的策略

1. 通过在URL中追加版本号或者作为查询字符串参数。
2. 通过Http自定义标头。
3. 多 个 版 本 的 Controller 共 处 在 一 个 项 目 中 ， 然 后 使 用 [RoutePrefix] 或 者 IHttpControllerSelector 根据报文头、路径等选择不同的 Controller 执行

Kubernetes采用的策略

Kubernetes采用的方案是通过URL中追加版本号来做多版本控制的。
下面是几个Kubernetes的API设计

POST /apis/batch/v1beta1/namespaces/{namespace}/cronjobs
POST /apis/apps/v1/namespaces/{namespace}/daemonsets

KubernetesAPI的版本号和废弃策略

• v1表示GA稳定版本；
• v1beta3表示Beta版本（预发布版本）；
• v1alpha1表示Alpha版本（实验性的版本）。

当某个API的实现达到一个新的GA稳定版本时（如v2），旧的GA版本（如v1）和Beta版本（例如v2beta1）将逐渐被废弃，Kubernetes建议废弃的时间如下。

1. 对于旧的GA版本（如v1），Kubernetes建议废弃的时间应不少于12个月或3个大版本Release的时间，选择最长的时间。
2. 对旧的Beta版本（如v2beta1），Kubernetes建议废弃的时间应不少于9个月或3个大版本Release的时间，选择最长的时间。
3. 对旧的Alpha版本，则无须等待，可以直接废弃。

分组的概念

为什么进行分组？

假如API不进行分组的话，管理和查询起来就会很麻烦，也不利于API的扩展。

KubernetesAPI是如何进行分组的？

Kubemetes 使用API Groups (API组)进行标识。

如果要启用或禁用特定的 API 组，则需要在 API Server 的启动参数中设置–runtime-config进行声明，例如–runtime-config=batch/v2alphal表示启用API组的 “batch/v2alpha1”，也可以设置–runtime-config=batch/v1=false表示禁用API组“batch/v1”。多个 API组的设置以逗号分隔。在当前的API Server服务中，DaemonSets、Deployments、HorizontalPodAutoscalers、Ingress、Jobs和ReplicaSets所属的 API 组是默认启用的。

访问控制

Kubernetes 对 API 访问提供了三种安全访问控制措施：认证、授权和 Admission Control。认证解决用户是谁的问题，授权解决用户能做什么的问题，Admission Control 则是资源管理方面的作用。通过合理的权限管理，能够保证系统的安全可靠。

Kubernetes 集群的所有操作基本上都是通过 kube-apiserver 这个组件进行的，它提供 HTTP RESTful 形式的 API 供集群内外客户端调用。

传输安全

在一个典型的 Kubernetes集群里， API 的侦听端口是443， TLS连接会被建立。 API server会提供一个证书。 这个证书是自签名的， 因此在 $USER/.kube/config路径下会包含API server证书的根证书，你可以指定这个证书用来替换系统默认的根证书。 当你使用kube-up.sh来创建集群时，这个证书会自动写入到$USER/.kube/config目录下。 如果集群有多个用户， 那么集群创建者需要和其它用户共享这个证书。

认证(Authentication)

• 开启TLS时，所有的请求首先需要认证。Kubernetes支持多种认证机制，并支持同时开启多个认证插件（只要有一个认证通过即可）。如果认证成功，则用户的username会传入授权模块做进一步授权验证；对于认证失败的请求则返回HTTP
  401。
• 当TLS建立时，HTTP请求会进行身份认证步骤，如图中步骤1，集群管理器将apiserver配置为运行一个或多个认证器模块。
• 认证模块包含客户端证书，密码、Plain Tokens、Bootstrap Tokens、JWT Tokens（used for
  service accounts）。我们可以指定多个认证模块，每个认证模块都会按顺序进行，直到其中一个成功。（在GCE上，客户端证书、密码、Plain Tokens和JWT Tokens都会启用。）

授权(Authorization)

当一个请求被验证来自指定用户时， 这个请求紧接着必须被授权， 即如图示中的步骤2所示. 一个请求必须包含请求者的用户名， 请求的动作， 影响动作的对象。 如果有存在的策略声明这个用户有权限完成这个动作，那么该请求就会被授权。 举个例子， 如果Bob用户有这样一条策略， 那么他可以从命名空间 projectCaribou中读取pod信息:

{"apiVersion": "abac.authorization.kubernetes.io/v1beta1","kind": "Policy","spec": {"user": "bob","namespace": "projectCaribou","resource": "pods","readonly": true}
}

如果Bob发送这样一个请求， 他可以被成功授权， 因为他读取命名空间 projectCaribou里的对象信息的动作是被允许的：

{"apiVersion": "authorization.k8s.io/v1beta1","kind": "SubjectAccessReview","spec": {"resourceAttributes": {"namespace": "projectCaribou","verb": "get","group": "unicorn.example.org","resource": "pods"}}
}

如果Bob发送往 projectCaribou命名空间写（create 或者 update）对象信息的请求， 那么他会被拒绝授权。 如果发送从一个不同的命名空间， 比如projectFish 读取(get)对象信息的请求，那么他的授权也会被拒绝。 Kubernetes的授权要求你和已存在的组织范畴或者云供应商范畴的访问控制系统进行交互时， 要使用通用的REST属性。使用REST的格式是非常重要的， 因为这些控制系统也可能会和包括Kubernetes API在内的其它API进行交互。 Kubernetes支持多个授权模块， 比如ABAC模式， RBAC模式， Webhook模式。 当一个管理员创建了集群， 他们会配置API server会启用哪些授权模块。 如果配置了多于1个的授权模块， Kubernetes会检查每个模块， 如果其中任何模块授权的请求， 请求会被处理， 如果所有的模块都拒绝了请求， 那么请求会被拒绝掉（返回403状态码）。

准入控制(Admission Control)

准入控制模块是可以修改或者拒绝请求的模块。 作为授权模块的补充， 准入控制可以访问一个正在被创建或更新的对象的内容， 它们在对象创建， 删除，更新， 连接（代理）期间起作用，在读取对象时它们不起作用。 可以配置多个准入控制器， 每个准入控制器会按照顺序被调用。 如图示中的步骤3所示。 跟认证和授权模块不同的时，如果任何一个准入控制模块拒绝了请求， 那么请求就会立马被拒绝掉。 除了拒绝对象之外， 准入控制器还可以为字段设置复杂的默认值。
一但一个请求通过了所有的准则控制器的批准， 那么这个请求会被对应的API对象验证程序证实为有效请求， 然后会被写入到对象存储里（如图中步骤 4所示）

安全端口和本地端口

之前的讨论的都是请求发往API Server的安全端口的情况（这个也是最典型的情况）。 事实上， API Server可以侦听两个端口： 默认情况下， API Server启动时侦听两个端口：
本地端口:

• 用于测试或者启动集群， 还有master 节点的其它组件跟API的交互
• 没有TLS
• 默认的侦听端口是8080，可以通过参数 --insecure-port 指定别的端口
• 默认绑定的IP是localhost， 可以通过参数 --insecure-bind-address指定别的地址
• 请求会绕过认证和授权模块
• 请求会经过准入控制模块处理
• 通过对主机进行访问控制保护接口

安全端口:

• 按需启用
• 使用 TLS. 通过 --tls-cert-file参数指定证书路径， --tls-private-key-file 参数指定证书的私钥
• 默认侦听6443端口， 可以通过--secure-port指定别的端口
• 默认IP绑定在第一个非localhost的网络接口， 可以通过--bind-address指定IP地址
• 请求会经过认证和授权模块的处理
• 请求会经过准入控制模块的处理
• 认证和授权模块会运行 如果在谷歌计算引擎平台(GCE)或者其他一些云提供商上用kube-up.sh创建集群的话， API Server会侦听443端口。 在GCE上， 默认会开放防火墙策略允许从外部通过HTTPS访问集群的API. 其它云供应商的策略不尽相同。

响应说明

状态码	编码	描述
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	IntemalServerError	表明服务端能被请求访问到，但是不能理解用户的请求:或者服务端内产生非预期中的一个错误，而且该错误无法被认知；或者服务端不能在一个合理的时间内完成处理（这可能由于服务器临时负载过重造成或者由于和其他服务器通信时的一个临时通信故障造成〉
503	ServiceUnavailable	表明被请求的服务无效。建议客户不要重试修改该请求
504	ServerTimeout	表明请求在给定的时间内无法完成.客户端仅在为请求指定超时( Timeout)参数时 会得到该响应

附

参考：
https://k8smeetup.github.io/docs/admin/accessing-the-api/
https://k8smeetup.github.io/docs/admin/admission-controllers/
http://docs.kubernetes.org.cn/27.html
https://kubernetes.io/zh/docs/reference/access-authn-authz/controlling-access/
https://www.cnblogs.com/yuxiaoba/p/9803284.html
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#container-v1-core
https://www.orchome.com/1360
https://blog.csdn.net/sherlockholmes11/article/details/102835313
https://www.kubernetes.org.cn/6794.html