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。

可参考：https://kubernetes.io/zh-cn/docs/reference/access-authn-authz/certificate-signing-requests/#normal-user

# 创建一个普通用户的私钥和证书签名请求 (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/

上篇：运维人员不得不看的K8S API入门实战，呕心沥血整理得又臭又长，有人看吗？