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

发布时间 2023-04-24 09:29:05作者: 不背锅运维

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//?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。

上图步骤的认证过程:

  1. 请求API时,会和APIServer建立TLS连接。
  2. 进入身份认证模块(Authentication),验证访问API的用户是否合法,认证不通过则返回401。
  3. 进入鉴权模块(Authorization),确认该用户是否具有访问某个资源或执行某个操作的权限, 如果现有策略声明该用户有权完成请求的操作,则鉴权通过。
  4. 进入准入控制器(Admission Control),执行验证和/或变更操作。
  5. 通过所有准入控制器后,再检查对应的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/

我打算分别使用Golang和Python的K8S客户端库来进行编码,今天的时间有限,放到下篇分享。

本文转载于WX公众号:不背锅运维(喜欢的盆友关注我们):https://mp.weixin.qq.com/s/G8jK0IBcfM3kxQfZD_ebEw