K8S API概述
可参考:https://kubernetes.io/zh-cn/docs/concepts/overview/kubernetes-api/
Kubernetes API是Kubernetes控制平面的核心。它是一组REST API,用于与Kubernetes中的各种对象进行交互,如Pods、Namespaces、ConfigMaps和Events等。通过这些API,可以查询和操作Kubernetes中API对象的状态。
API server是Kubernetes集群中的一个组件,它公开了这些REST API。Kubernetes中的各种组件,包括kubectl命令行工具、kubeadm等工具,都通过调用这些API来执行操作。
除了使用kubectl等工具之外,也可以直接使用REST调用来访问API。如果正在编写使用Kubernetes API的应用程序,请考虑使用其中一个客户端库。
完整的API详细信息都使用OpenAPI进行文档化,这使得运维开发人员可以很容易地了解API的功能和使用方式。
OpenAPI 规范
Kubernetes OpenAPI 规范实际上只有一种,它是基于 OpenAPI 3.0 规范的。之前版本的 Kubernetes API 使用的是 Swagger 2.0 规范,但现在已经升级到了 OpenAPI 3.0 规范。
需要注意的是,虽然 OpenAPI 3.0 规范是 Swagger 2.0 规范的继承者,但它们之间有一些重要的区别,如参数、响应、请求体和安全等方面的定义方式都有所不同。因此,在使用 OpenAPI 规范时需要注意版本兼容性。接下来,分别了解一下V2和V3。
OpenAPI V2
Kubernetes API服务器提供了一个聚合的 OpenAPI v2 规范,通过访问 /openapi/v2 端点获取。这个规范包括了所有的API组的定义,以及每个API组的所有API的定义,使得运维开发人员可以清楚地了解Kubernetes API的结构和功能。
通过在HTTP请求头中指定不同的响应格式,运维开发人员可以获得不同格式的OpenAPI规范文档。下表列出了可用的请求头和响应格式:
头部 | 可选值 | 说明 |
Accept-Encoding | gzip | 不指定此头部也是可以的 |
Accept | application/com.github.proto-openapi.spec.v2@v1.0+protobuf | 主要用于集群内部 |
application/json | 默认值 | |
* | 提供application/json |
通过使用这些请求头,开发人员可以获取他们所需的格式化的OpenAPI规范文档,以便在应用程序中进行处理和解析。
Kubernetes的API使用Protobuf作为序列化格式进行内部通信。这种序列化格式有助于减少网络传输的数据量和提高通信的效率。在Kubernetes中,每个API对象都有一个对应的Protobuf定义文件。这些文件描述了对象的结构和字段。Kubernetes还提供了使用这些Protobuf定义文件生成客户端和服务器代码的工具,以便开发人员可以轻松地使用Kubernetes API。除了Protobuf之外,Kubernetes还支持使用其他序列化格式进行通信,例如JSON和YAML。这些格式更易于阅读和编写,并且通常用于与外部系统的集成。不过,在集群内部通信时,Protobuf仍然是最常用的序列化格式。
想进一步了解 Kubernetes Protobuf 序列化可参考:https://github.com/kubernetes/design-proposals-archive/blob/main/api-machinery/protobuf.md
OpenAPI V3
OpenAPI V3是Kubernetes支持的一种API描述格式。从Kubernetes v1.27版本开始,这个功能已经被稳定支持。
Kubernetes提供了一个名为 /discovery/v3 的端点来展示所有可用的API组和版本列表。这个端点只返回JSON格式的数据。这些API组和版本会以特定的格式呈现:
{ "paths": { ..., "api/v1": { "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF" }, "apis/admissionregistration.k8s.io/v1": { "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597" }, .... } }
为了提高客户端缓存效率,这些相对URL指向不可变的OpenAPI描述信息。为此,API服务器还设置了适当的HTTP缓存标头(将Expires设置到未来的1年,将Cache-Control设置为不可变)。当使用过时的URL时,API服务器会将其重定向到最新的URL。
Kubernetes API服务器在 /openapi/v3/apis/<group>/<version>?hash=<hash> 端点为每个Kubernetes组版本发布一个OpenAPI v3规范。
接受的请求标头请参考下表:
头部 | 可选值 | 说明 |
Accept-Encoding | gzip | 不提供此头部也是可接受的 |
Accept | application/com.github.proto-openapi.spec.v3@v1.0+protobuf | 主要用于集群内部使用 |
application/json | 默认 | |
* | 以 application/json 形式返回 |
API参考
API 端点、资源类型以及示例可参考: https://kubernetes.io/zh-cn/docs/reference/kubernetes-api/
请求API经历的阶段
可参考:https://kubernetes.io/zh-cn/docs/concepts/security/controlling-access/
用户可以使用kubectl、客户端库或通过进行REST请求来访问Kubernetes API。无论是人类用户还是Kubernetes服务账户,都可以被授权访问API。当请求到达API时,它会经过几个阶段,如下图所示:
连接和证书:
- API Server默认在6443端口上进行监听,也可以修改。
- 访问API,使用TLS建立连接。
- API Server证书,可以是私有CA、也可以是公认CA。
上图步骤的认证过程:
- 请求API时,会和APIServer建立TLS连接。
- 进入身份认证模块(Authentication),验证访问API的用户是否合法,认证不通过则返回401。
- 进入鉴权模块(Authorization),确认该用户是否具有访问某个资源或执行某个操作的权限, 如果现有策略声明该用户有权完成请求的操作,则鉴权通过。
- 进入准入控制器(Admission Control),执行验证和/或变更操作。
- 通过所有准入控制器后,再检查对应的API对象,然后将其写入对象存储。
“鉴权模块说明:鉴权模块的实现有RBAC、ABAC、Node、Webhook。可参考:https://kubernetes.io/zh-cn/docs/reference/access-authn-authz/authorization/
” “准入控制器说明:准入控制器会在请求通过认证和鉴权之后、对象被持久化之前拦截到达 APIServer的请求,准入控制过程会运行两个阶段,分别是第1阶段是运行变更准入控制器,第2阶段是运行验证准入控制器。注意了,某些控制器既是变更准入控制器又是验证准入控制器。如果两个阶段之一的任何一个控制器拒绝了某请求,则整个请求将立即被拒绝,并向最终用户返回错误。如要进一步了解准入控制器可参考:https://kubernetes.io/zh-cn/docs/reference/access-authn-authz/admission-controllers/
”
请求API之前准备一个普通用户
所有 Kubernetes 集群都有两类用户:
- 由 Kubernetes 管理的服务账号
- 普通用户
在实际工作中要调用K8S API,为了增加安全性,建议创建一个专用的普通程序账号。
1. 创建普通用户的私钥
为了让普通用户能够通过认证并调用API,需要执行几个步骤。首先,该用户必须拥有Kubernetes集群签发的证书,然后将该证书提供给Kubernetes API。
# 创建一个普通用户的私钥和证书签名请求 (Certificate Signing Request, CSR)。可以使用 OpenSSL 工具生成私钥和 CSR: openssl genrsa -out tantianran.key 2048 openssl req -new -key tantianran.key -out tantianran.csr -subj "/CN=tantianran/O=noblameops"
这里 tantianran 是用户的名称,noblameops 是用户所属的组织。
2. 创建证书签名请求(CertificateSigningRequest),并提交到Kubernetes集群
将 CSR 提交给 Kubernetes 集群中的证书签名机构 (Certificate Authority, CA) 进行签名。可以使用 kubectl 工具提交 CSR 并获取签名后的证书:
cat <<EOF | kubectl apply -f - apiVersion: certificates.k8s.io/v1 kind: CertificateSigningRequest metadata: name: tantianran spec: request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ2J6Q0NBVmNDQVFBd0tqRVRNQkVHQTFVRUF3d0tkR0Z1ZEdsaGJuSmhiakVUTUJFR0ExVUVDZ3dLYm05aQpiR0Z0Wlc5d2N6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQU1Jc0M0R2JSQ0NJCmE1L2RLenpYc3VtUXVxay9qclZRemJuSmpiVkY5ZVV6bU1OR3drTi9aanRrVU5ZTUNRMkRpY1JIRUJzTFVMTTIKSFhTdkZtV1lUUGN6OEJWOHgvR214YXlWcVNmQTU4aDNtdjJERjhZdFB2aFlVc3hmUVZpUUxFRGFwRXpoV29TcApVN3BwRjJ4YXZjeG9GbDd3emRQWE9YMnhDQXNSQ3pINjB6cG9zSEJiNHBaSGJjYjNyQ1hjdHBnVlFDeklubWRGCjFrNHJncHg5SGsrek4rNzQ1R04vS1dMMWdLcFNhN2YxemdHdXVaT2FrZEhKaldGdCtWYzNFSG90SFQ3V3g1VTEKazV4ZnpuZkk2VlkvN0NTbzR1K2hhSTg2RHBRaXZmdk1OM3ZGeURwOVR2UWVsOFJpZlFiMkxaMnlUYzdEL3hHQQpCWUZhQ25OUjl3a0NBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUJDd1VBQTRJQkFRQ0hyNmYxd3A0NFd1L1dtczAvCmRFdWswVjJrMElzQzZoOHppbkptN3BHMjlpSFVrVDZNWDNBR3E0WlVZNkVBN3BYa1VDazhsYXFGVjVQTmJoSXkKUTBEUndRdW82WHNqZ1JMQmdZZFNRaU5vVUYrR1ZCSEEyNmZEV3c2VU8zdjErZXVJODlOWXVJbXl4UGtpaE0xYgpyZkNoa1RCeXRBbUxHbVlwOU5OMnBHdDJyTW94cGtDME5PSElWOWdPUnp1Q1h3cytWTE5zS3VSS2diT1hsUVhMCmVOeVd4TGlCR0ZSZ1BsaWpyTnQrdnA1WktHRjV1SEVXYStjZ3NXN1cwZCtoRm9XMlYxczVDZ2ZzdU1IdUNlR3AKMUxSVnZheVJSaDVtekdnTlNrdUpkUTBHdU1lbk5tRGpoSDI1NU5CNVBzdHpTOVBSU1lCVUIvdUdIYi9yVXByWgprOHRECi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo= signerName: kubernetes.io/kube-apiserver-client expirationSeconds: 86400 # one day usages: - client auth EOF
需要注意的几点:
- usage 字段必须是 'client auth'
- expirationSeconds 可以设置为更长(例如 864000 是十天)或者更短(例如 3600 是一个小时)
- request 字段是 CSR 文件内容的 base64 编码值。 要得到该值,可以执行命令
cat tantianran.csr | base64 | tr -d "\n"
创建完成后查看一下CSR列表:
[root@k8s-a-master api-user]# kubectl get csr NAME AGE SIGNERNAME REQUESTOR REQUESTEDDURATION CONDITION tantianran 58s kubernetes.io/kube-apiserver-client kubernetes-admin 24h Pending
3. 批准证书签名请求(CertificateSigningRequest,简称CSR)
[root@k8s-a-master api-user]# kubectl certificate approve tantianran certificatesigningrequest.certificates.k8s.io/tantianran approved
反之,如果要驳回:
kubectl certificate deny tantianran
4. 获取证书
从CSR获取证书:
kubectl get csr/tantianran -o yaml
证书的内容使用 base64 编码,存放在字段 status.certificate。
从 CertificateSigningRequest 导出颁发的证书:
kubectl get csr tantianran -o jsonpath='{.status.certificate}'| base64 -d > tantianran.crt
5. 基于RBAC的鉴权模式,创建Role(角色)
“在 Kubernetes 中,Role 和 ClusterRole 都是用于授权访问 Kubernetes API 资源的对象,但它们之间有着不同的作用域。Role 是一个名字空间作用域的资源,它定义了一个角色,即一组操作权限,可以被授予给一个或多个用户、服务账户或其他角色,以控制它们在某个特定命名空间内的操作权限。因此,当您创建 Role 时,必须指定该 Role 所属的命名空间。与之相对,ClusterRole 是一个集群作用域的资源,它定义了一组操作权限,可以授予给任何命名空间内的用户、服务账户或其他角色。因此,ClusterRole 可以用于授权对整个 Kubernetes 集群的操作权限。需要注意的是,由于 Kubernetes 对象要么是名字空间作用域的,要么是集群作用域的,因此 Role 和 ClusterRole 的名称不同,以便将它们区分开来。如果您要在特定的命名空间内设置访问权限,则应该使用 Role。如果您要在整个集群中设置访问权限,则应该使用 ClusterRole。
”
创建了证书之后,为了让这个用户能访问 Kubernetes 集群资源,现在就要创建 Role 和 RoleBinding(在下一小节创建) 了。
下面命令将在 rook-ceph 命名空间中创建一个名为 developer 的角色,并为该角色分配一些操作权限。具体来说,该角色将被授予在该命名空间内创建、获取、列出、更新和删除 pods 资源的权限。
kubectl create role developer --verb=create --verb=get --verb=list --verb=update --verb=delete --namespace=rook-ceph --resource=pods
- kubectl create role developer:创建一个名为 developer 的角色。
- --verb=create --verb=get --verb=list --verb=update --verb=delete:指定该角色允许的操作权限,即创建、获取、列出、更新和删除。
- --namespace=rook-ceph:指定该角色所属的命名空间为 rook-ceph。
- --resource=pods:指定该角色所授权的资源类型为 pods。
对应的yaml如下:
apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: developer namespace: rook-ceph rules: - apiGroups: - "" resources: - pods verbs: - create - get - list - update - delete
列出rook-ceph命名空间下的role:
[root@k8s-a-master api-user]# kubectl get roles -n rook-ceph NAME CREATED AT cephfs-external-provisioner-cfg 2023-04-03T08:28:33Z developer 2023-04-19T08:10:25Z # 这个就是刚才创建的 rbd-csi-nodeplugin 2023-04-03T08:28:33Z rbd-external-provisioner-cfg 2023-04-03T08:28:33Z rook-ceph-cmd-reporter 2023-04-03T08:28:33Z rook-ceph-mgr 2023-04-03T08:28:33Z rook-ceph-osd 2023-04-03T08:28:33Z rook-ceph-purge-osd 2023-04-03T08:28:33Z rook-ceph-rgw 2023-04-03T08:28:33Z rook-ceph-system 2023-04-03T08:28:33Z
6. 基于RBAC的鉴权模式,创建 RoleBinding (角色绑定)
“角色绑定(Role Binding)是将角色中定义的权限赋予一个或者一组用户。 它包含若干 主体(用户、组或服务账户)的列表和对这些主体所获得的角色的引用。 RoleBinding 在指定的名字空间中执行授权,而 ClusterRoleBinding 在集群范围执行授权。一个 RoleBinding 可以引用同一的名字空间中的任何 Role。 或者,一个 RoleBinding 可以引用某 ClusterRole 并将该 ClusterRole 绑定到 RoleBinding 所在的名字空间。 如果你希望将某 ClusterRole 绑定到集群中所有名字空间,你要使用 ClusterRoleBinding。
”
下面的命令是在Kubernetes集群中创建一个名为developer-binding-tantianran的角色绑定对象,其作用是将一个用户(tantianran)与一个名为developer的角色关联起来。
kubectl create rolebinding developer-binding-tantianran --role=developer --user=tantianran --namespace=rook-ceph
- --role选项指定了要绑定的角色,这里是developer。
- --user选项指定了要绑定到该角色的用户,这里是tantianran。
这意味着,一旦角色绑定对象被创建,用户tantianran就将获得developer角色的权限。
对应的yaml如下:
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: developer-binding-tantianran namespace: rook-ceph roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: developer subjects: - apiGroup: rbac.authorization.k8s.io kind: User name: tantianran
列出rook-ceph命名空间下的RoleBinding:
[root@k8s-a-master api-user]# kubectl get rolebinding -n rook-ceph NAME ROLE AGE cephfs-csi-provisioner-role-cfg Role/cephfs-external-provisioner-cfg 15d developer-binding-tantianran Role/developer 14s # 这个是刚才创建的 rbd-csi-nodeplugin-role-cfg Role/rbd-csi-nodeplugin 15d rbd-csi-provisioner-role-cfg Role/rbd-external-provisioner-cfg 15d rook-ceph-cluster-mgmt ClusterRole/rook-ceph-cluster-mgmt 15d rook-ceph-cmd-reporter Role/rook-ceph-cmd-reporter 15d rook-ceph-mgr Role/rook-ceph-mgr 15d rook-ceph-mgr-system ClusterRole/rook-ceph-mgr-system 15d rook-ceph-osd Role/rook-ceph-osd 15d rook-ceph-purge-osd Role/rook-ceph-purge-osd 15d rook-ceph-rgw Role/rook-ceph-rgw 15d rook-ceph-system Role/rook-ceph-system 15d
7. 添加到kubeconfig
kubeconfig 是 Kubernetes 集群客户端的配置文件,它包含连接到 Kubernetes API Server 所需的信息,包括 API Server 地址、证书、认证方式等。
最后一步是将这个用户添加到 kubeconfig文件。首先,需要添加新的凭据:
kubectl config set-credentials tantianran --client-key=tantianran.key --client-certificate=tantianran.crt --embed-certs=true --namespace=rook-ceph
- tantianran 是用户凭据条目的名称,可以自定义。
- --client-key=tantianran.key 表示使用名为 tantianran.key 的客户端密钥文件作为用户凭据的一部分。客户端密钥用于对 API 服务器进行身份验证。
- --client-certificate=tantianran.crt 表示使用名为 tantianran.crt 的客户端证书文件作为用户凭据的一部分。客户端证书用于对 API 服务器进行身份验证。
- --embed-certs=true 表示将客户端证书嵌入到 kubeconfig 文件中,而不是将其作为文件引用。这可以帮助简化 kubeconfig 文件的管理。
- --namespace=rook-ceph 表示在 rook-ceph 命名空间中使用该用户凭据。命名空间用于将 Kubernetes 资源划分为不同的逻辑组。
使用 kubectl config set-credentials 命令创建了名为 tantianran 的用户凭据,那么可以在输出结果中搜索 tantianran 来查看该用户凭据的详细信息。下面是使用 kubectl config view 命令查看 kubeconfig 文件中用户凭据的示例输出:
[root@k8s-a-master api-user]# kubectl config view apiVersion: v1 clusters: - cluster: certificate-authority-data: DATA+OMITTED server: https://192.168.11.10:6443 name: kubernetes contexts: - context: cluster: kubernetes user: kubernetes-admin name: kubernetes-admin@kubernetes - context: cluster: kubernetes user: tantianran name: tantianran current-context: kubernetes-admin@kubernetes kind: Config preferences: {} users: - name: kubernetes-admin user: client-certificate-data: REDACTED client-key-data: REDACTED - name: tantianran user: client-certificate-data: REDACTED client-key-data: REDACTED
在上述输出中,可以看到名为 tantianran 的用户凭据信息,包括客户端证书、客户端密钥和命名空间等。
然后,添加上下文:
kubectl config set-context tantianran --cluster=kubernetes --user=tantianran --namespace=rook-ceph
kubectl config set-context 命令用于创建或修改 kubeconfig 文件中的上下文。上下文包含了与一个 Kubernetes 集群的连接所需的所有信息,包括集群、用户和命名空间等。上面的参数说明如下:
- tantianran 是上下文的名称
- --cluster 参数指定了集群名称为 kubernetes
- --user 参数指定了用户名称为 tantianran
- --namespace 参数指定了默认命名空间为 rook-ceph。 简而言之,这个命令创建了一个名为 tantianran 的上下文,该上下文与 kubernetes 集群建立连接,并使用 tantianran 用户进行身份验证。同时,该上下文默认的命名空间为 rook-ceph,经过实战,其实是没必要指定命名空间。因为,就算指定了命名空间,当不管是查看还是删除上下文的时候,不管有没有指定命名空间都是可以的。比如查看的时候,不指定命名空间也能查到,比如删除的时候,不指定命名空间照样也能删除。
如果要删除上下文可以用下面的命令:
kubectl config delete-context tantianran # 或 kubectl config delete-context tantianran -n rook-ceph
添加后,查看当前可用的 Kubernetes 配置文件上下文:
[root@k8s-a-master api-user]# kubectl config get-contexts CURRENT NAME CLUSTER AUTHINFO NAMESPACE * kubernetes-admin@kubernetes kubernetes kubernetes-admin tantianran kubernetes tantianran rook-ceph # 或 [root@k8s-a-master api-user]# kubectl config get-contexts -n rook-ceph CURRENT NAME CLUSTER AUTHINFO NAMESPACE * kubernetes-admin@kubernetes kubernetes kubernetes-admin tantianran kubernetes tantianran rook-ceph [root@k8s-a-master api-user]#
上下文切换:
# 切换到普通用户的上下文 [root@k8s-a-master api-user]# kubectl config use-context tantianran # 列出当前上下文 [root@k8s-a-master api-user]# kubectl config get-contexts CURRENT NAME CLUSTER AUTHINFO NAMESPACE kubernetes-admin@kubernetes kubernetes kubernetes-admin * tantianran kubernetes tantianran # 此处的*号代表当前上下文是处于这个账户下 # 把上下文切换回admin: kubectl config use-context kubernetes-admin@kubernetes
查看当前用户是否可以执行给定操作(无论使用何种鉴权模式该命令都可以工作,我这里是RBAC(基于角色的访问控制)的鉴权模式):
# 在admin上下文中执行查看操作: [root@k8s-a-master api-user]# kubectl auth can-i list pods --namespace rook-ceph --as tantianran yes [root@k8s-a-master api-user]# kubectl auth can-i list pods --namespace default --as tantianran # 可以看到,处于default命名空间下的pod的,tantianran是没有权限的 no # 如果已经切换到了普通账户的上下文中,那么可以用下面的命令查看: [root@k8s-a-master api-user]# kubectl config use-context tantianran [root@k8s-a-master api-user]# kubectl auth can-i create pods --namespace rook-ceph yes [root@k8s-a-master api-user]# kubectl auth can-i create pods --namespace default no
客户端库
当要使用 Kubernetes REST API 来操作K8S各种资源时,可以根据自己喜欢的编程语言来选择合适的客户端库。客户端库有官方支持的,也有社区维护的。官方支持的 Kubernetes 客户端库有Go、Python、C、Java等等,作为运维开发工程师,可以使用Go或者Python。而我,以前是写Python的,老早就已经彻底转Go了,而且还是Go的深度发烧友。关于客户端库更多的信息可参考:https://kubernetes.io/zh-cn/docs/reference/using-api/client-libraries/