这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

资源检索

Clusterpedia 支持对 多个集群内资源指定集群的资源 以及聚合资源 的复杂检索,

并且这些复杂检索的条件可以通过两种方式传递给 Clusterpedia APIServer

  • URL Query:直接将查询条件作为 Query 来传递
  • Search Labels:为了兼容 Kubernetes OpenAPI,可以将查询条件设置在 Label Selector。

Search LabelsURL Query 都支持与 Label Selector 相同的操作符:

  • existnot exist
  • ===!=
  • innotin

除了条件检索,Clusterpedia 还增强了 Field Selector ,满足我们通过 metadata.annotation 或者 status.* 等字段的过滤需求。

元信息检索

支持的操作符:===in

作用 search label key url query
过滤集群名称 search.clusterpedia.io/clusters clusters
过滤命名空间 search.clusterpedia.io/namespaces namespaces
过滤资源名称 search.clusterpedia.io/names names

暂时不支持例如 !=notin 操作符,如果有这些需求或者场景,可以在 issue 中讨论

模糊搜索

支持的操作符:===in

该功能暂时为试验性功能,暂时只提供 search label

作用 search label key url query
模糊搜索资源名称 internalstorage.clusterpedia.io/fuzzy-name -

创建时间区间检索

支持的操作符:===

基于资源的创建时间区间进行检索,采用的是左闭右开的区间

作用 search label key url query
指定 Since search.clusterpedia.io/since since
指定 Before search.clusterpedia.io/before before

创建时间的格式有四种:

  1. Unix 时间戳格式 为了方便使用会根据时间戳的长度来区分单位为 s 还是 ms。 10 位时间戳单位为秒,13 位时间戳单位为毫秒。
  2. RFC3339 2006-01-02T15:04:05Z or 2006-01-02T15:04:05+08:00
  3. UTC Date 2006-01-02
  4. UTC Datetime 2006-01-02 15:04:05

由于 kube label selector 的限制,search label 只支持 Unix 时间戳UTC Date.

使用 url query 的方式可以所有的格式

Owner 检索

只支持操作符:===

作用 search label key url query
指定 Owner UID search.clusterpedia.io/owner-uid ownerUID
指定 Owner Name search.clusterpedia.io/owner-name ownerName
指定 Owner Group Resource search.clusterpedia.io/owner-gr ownerGR
指定 Owner 辈分 internalstorage.clusterpedia.io/owner-seniority ownerSeniority

需要注意指定 Owner UID 时,Owner NameOwner Group Resource 会被忽略

Owner Group 的格式为 resource.group,例如 deployments.apps 或者 nodes

排序

只支持操作符:===in

作用 search label key url query
多字段排序 search.clusterpedia.io/orderby orderby

分页

只支持操作符 ===

作用 search label key url query
设置分页 size search.clusterpedia.io/size limit
设置分页 offset search.clusterpedia.io/offset continue
要求响应携带 Continue search.clusterpedia.io/with-continue withContinue
要求响应携带资源剩余数量 search.clusterpedia.io/with-remaining-count withRemainingCount

在使用 kubectl 操作时,分页 size 只能通过 kubectl --chunk-size 来设置,因为 kubectl 会将 limit 默认设置为 500。

Label 过滤

无论使用 kubectl 还是 URL,所有 Key 中不包含 clusterpedia.io 的 Label Selector 都会作为 Label Selector 来过滤资源。

所有行为和原生 Kubernetes 一致。

作用 kubectl url query
Label 过滤 kubectl -l or kubectl --label-selector labelSelector

字段过滤

Clusterpedia 的 Field Selector 在操作符上与 Label Selector 保持一致,同样支持:

existnot exist===!=innotin

无论是 URL 还是 kubectl 上的命令参数都原生 Field Selector 一致

作用 kubectl url query
字段过滤 kubectl --field-selector fieldSelector

详细可以查看:

高级检索(自定义条件检索)

自定义检索为 默认存储层 提供的功能,目的是为了满足用户更加灵活多变的检索需求

作用 search label key url query
自定义检索语句 - whereSQL

自定义检索并不支持通过 search lable,只能使用 url query 来传递自定义搜素的语句。

另外该功能暂时还是处于 alpha 阶段,需要用户在 clusterpedia apiserver 中开启相应的 Feature Gate,详细可以参考 自定义条件检索

CollectionResource URL Query

以下 URL Query 专属于 Collection Resource。

作用 url query example
只获取资源的 metadata onlyMetadata onlyMetadata=true
指定 any collectionresource 的 groups groups groups=apps,cert-manager.io/v1
指定 any collectionresource 的 resources resources resources=apps/deployments,batch/v1/cronjobs

1 - 多集群检索

多集群资源检索可以满足我们根据查询条件一次过滤多个集群内的资源,并提供对这些资源的分页排序的能力

在使用 kubectl 操作时,可以查看一下当前可以检索哪些资源

kubectl --cluster clusterpedia api-resources
# 输出:
NAME          SHORTNAMES   APIVERSION           NAMESPACED   KIND
configmaps    cm           v1                   true         ConfigMap
namespaces    ns           v1                   false        Namespace
nodes         no           v1                   false        Node
pods          po           v1                   true         Pod
secrets                    v1                   true         Secret
daemonsets    ds           apps/v1              true         DaemonSet
deployments   deploy       apps/v1              true         Deployment
replicasets   rs           apps/v1              true         ReplicaSet
issuers                    cert-manager.io/v1   true         Issuer

Clusterpedia 根据所有集群同步的资源来提供多集群的资源检索,可以查看 同步集群资源 来更新需要同步的资源

基本功能

指定集群

多集群检索时,会默认检索所有的集群,我们也可以指定单个或者一组集群

使用 Search Label search.clusterpedia.io/clusters 来指定一组集群

kubectl --cluster clusterpedia get deployments -l "search.clusterpedia.io/clusters in (cluster-1,cluster-2)"
# 输出:
NAMESPACE     CLUSTER     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   cluster-1   coredns                   2/2     2            2           68d
kube-system   cluster-2   coredns                   2/2     2            2           64d

对于指定单个集群的检索,同样可以使用 Search Label 来设置,也可以查看 指定集群检索 来使用 URL Path 的方式指定集群

# 指定单个集群
kubectl --cluster clusterpedia get deployments -l "search.clusterpedia.io/clusters=cluster-1"

# 指定集群也可以使用 --cluster <cluster name> 来指定
kubectl --cluster cluster-1 get deployments

使用 URL 时,使用 clusters 作为 URL Query 来传递

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?clusters=cluster-1"

如果指定单个集群,也可以将 cluster name 放到 URL 路径中

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/clusters/cluster-1/apis/apps/v1/deployments"

了解更多指定集群检索

指定命名空间

可以像查看原生 Kube 一样来指定单个命名空间或者所有命名空间

使用 -n <namespace> 来指定命名空间,默认在 default 命名空间

kubectl --cluster clusterpedia get deployments -n kube-system
# 输出:
CLUSTER     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
cluster-1   coredns                   2/2     2            2           68d
cluster-2   calico-kube-controllers   1/1     1            1           64d
cluster-2   coredns                   2/2     2            2           64d

使用 -A 或者 --all-namespaces 来查看所有集群的所有命名空间下的资源

kubectl --cluster clusterpedia get deployments -A
# 输出:
NAMESPACE     CLUSTER     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   cluster-1   coredns                   2/2     2            2           68d
kube-system   cluster-2   calico-kube-controllers   1/1     1            1           64d
kube-system   cluster-2   coredns                   2/2     2            2           64d
default       cluster-2   dd-airflow-scheduler      0/1     1            0           54d
default       cluster-2   dd-airflow-web            0/1     1            0           54d

获取资源的 URL Path 和原生 Kubernetes 一样 /apis/apps/v1/deployments

只是需要加上 Clusterpedia Resources 的路径前缀 /apis/clusterpedia.io/v1beta1/resources 来表示当前是 Clusterpedia 请求。

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments"

# 指定命名空间
kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/namespaces/kube-system/deployments"

除了指定单个命名空间,还可以指定查看一组命名空间下的资源

使用 Search Label search.clusterpedia.io/namespaces 来指定一组命名空间

一定要指定 -A 参数,避免 kubectl 在路径中设置 default namespace

kubectl --cluster clusterpedia get deployments -A -l "search.clusterpedia.io/namespaces in (kube-system, default)"
# 输出:
NAMESPACE     CLUSTER     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   cluster-1   coredns                   2/2     2            2           68d
kube-system   cluster-2   calico-kube-controllers   1/1     1            1           64d
kube-system   cluster-2   coredns                   2/2     2            2           64d
default       cluster-2   dd-airflow-scheduler      0/1     1            0           54d
default       cluster-2   dd-airflow-web            0/1     1            0           54d

使用 URL 时,就不需要使用 Label Selector 来传递参数了,直接使用 URL Query namespaces 即可

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?namespaces=kube-system,default"

指定资源名称

用户可以通过一组资源名称来过滤资源

使用 Search Label search.clusterpedia.io/names 来指定一组资源名称 注意:如果在所有命名空间下检索资源,需要指定 -A 参数,或者使用 -n 来指定命名空间

kubectl --cluster clusterpedia get deployments -A -l "search.clusterpedia.io/names=coredns"
# 输出:
NAMESPACE     CLUSTER     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   cluster-1   coredns                   2/2     2            2           68d
kube-system   cluster-2   coredns                   2/2     2            2           64d

使用 URL 时,使用 names 作为 URL Query 来传递,如果需要指定命名空间,那么就在路径中加上 namespace。

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?names=kube-coredns,dd-airflow-web"

# 在 default 命名空间下检索指定名字的资源
kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/namespaces/default/deployments?names=kube-coredns,dd-airflow-web"

在多集群检索时,返回的数据实际是以类似 DeploymentList 的结构封装的数据。

如果我们想要获取到单个的 Deployment 那么就需要在 URL 路径中指定 cluster name,参考获取单个资源

创建时间的区间

创建时间的区间以左闭右开的方式来进行检索,since <= creation time < before

关于详细的时间区间参数可以查看 创建时间区间检索

使用 Search Label search.clusterpedia.io/sincesearch.clusterpedia.io/before 来指定时间区间

kubectl --cluster clusterpedia get deployments -A -l "search.clusterpedia.io/since=2022-03-24, \
    search.clusterpedia.io/before=2022-04-10"

直接使用 URL 时,可以 Query sincebefore 来分别指定时间的区间

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?since=2022-03-24&before=2022-04-10"

模糊搜索

当前支持根据资源名称进行模糊搜索,由于模糊搜索还需要继续讨论,所以暂时以试验性功能来提供

只支持 Search Label 的方式,不支持 URL Query

kubectl --cluster clusterpedia get deployments -A -l "internalstorage.clusterpedia.io/fuzzy-name=test"

过滤出名字中包含 test 字符串的 deployments。

可以使用 in 操作符来传递多个参数,这样可以过滤出名字中包含所有字符串的资源

字段过滤

原生 Kubernetes 当前只支持对 metadata.namemetadata.namespace 的字段过滤,而且操作符只支持 =!===,能力非常有限。

Clusterpedia 在兼容已有的 Field Selector 功能的基础上,提供了更加强大的功能,支持和 Label Selector 相同的操作符。

Field Selector 的 key 当前支持三种格式:

  • 使用 . 分隔字段
kubectl --cluster clusterpedia get pods --field-selector="status.phase=Running"

# 也可以在首字符添加 `.`
kubectl --cluster clusterpedia get pods --field-selector=".status.phase notin (Running,Succeeded)"
  • 字段名称使用 '' 或者 "" 来包裹,可以用于带 . 之类的非法字符的字段
kubectl --cluster clusterpedia get deploy \
    --field-selector="metadata.annotations['test.io'] in (value1,value2),spec.replica=3"
  • 使用 [] 来分隔字段[] 内字符串必须使用 '' 或者 "" 来包裹
kubectl --cluster clusterpedia get pods --field-selector="status['phase']!=Running"

列表字段支持

实际在字段过滤的设计时考虑到了对列表元素内字段过滤,不过由于使用场景是否真正有意义还需要更多的讨论 issue: support list field filtering

示例:

kubectl get po --field-selector="spec.containers[].name!=container1"

kubectl get po --field-selector="spec.containers[].name == container1"

kubectl get po --field-selector="spec.containers[1].name in (container1,container2)"

根据父辈以及祖辈 Owner 查询

通过 Owner 检索是一个非常有用的检索功能, 并且 Clusterpedia 在 Owner 的基础上还支持对 Owner 进行辈分提升来进行祖辈甚至更高辈分的检索

通过 Owner 检索,可以一次查询到 Deployment 下的所有 Pods,无需中间再查询 ReplicaSet

Owner 查询必须指定单个集群,可以使用 Serach Label 或者 URL Query 来指定,也可以在 URL Path 中指定集群名称

关于根据 Owner 检索的具体使用方法,可以参考指定集群内根据父辈或者祖辈 Owenr 进行检索

分页与排序

分页和排序是资源检索必不可少的功能

根据多个字段进行排序

可以指定多个字段进行排序,而对排序字段的支持是由存储层来决定。

当前默认存储层支持对 clusternamespacenamecreated_atresource_version 进行正序和倒序的排序,字段也支持随意的组合

使用多个字段进行正序排序

kubectl --cluster clusterpedia get pods -l \
    "search.clusterpedia.io/orderby in (cluster, name)"

由于 Label Selector 对 value 的限制,倒序时需要在字段结尾加上 _desc

kubectl --cluster clusterpedia get pods -l \
    "search.clusterpedia.io/orderby in (namespace_desc, cluster, name)"

使用 URL Query 来指定排序字段

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?orderby=namespace,cluster"

指定倒序字段时,在字段后添加 desc,以空格分隔

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?orderby=namespace desc,cluster"

分页

原生 Kubernetes 实际是支持分页的,ListOptions 中便已经存在用于分页查询的字段。

Clusterpedia 复用 ListOptions.LimitListOptions.Continue 字段作为分页的 sizeoffset

kubectl 的 --chunk-size 实际通过设置 limit 来用于分片拉取。

原生的 Kubernetes APIServer 会在返回的响应中携带用于下一次拉取的 continue, 并根据 --chunk-sizeconintue 进行下一次拉取,直到相应的数据中 Conintue 为空。

Clusterpedia 为了保证在 kubectl 中实现分页检索,默认并不会在响应中返回 continue 字段,这样避免了 kubectl 使用分片拉取全部数据

kubectl --cluster cluster-1 get pods --chunk-size 10

需要注意 kubectl 在不设置 --chunk-size 的情况下,limit 会被设置成默认值 500, 也就是说 search.clusterpedia.io/size 实际是无法生效的,只是用于和 search.clusterpedia.io/offset 形成对应关系

URL Query 的优先级大于 Search Label

在 kubectl 中 continue 是没有 flag 可以设置的。所以还是要使用 Search Label 来传递。

kubectl --cluster clusterpedia get pods --chunk-size 10 -l \
    "search.clusterpedia.io/offset=10"

对资源进行分页检索,只需要在 URL 中设置 limitcontinue 即可

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?limit=10&continue=5"

响应携带 Continue 信息

响应数据的 ListMeta.Continue 可以用于 ListOptions.Continue 中作为下一次拉取的 offset

分页功能中我们提到,为了避免 kubectl 进行对全量数据的分片拉取,Clusterepdia 不会在响应中携带 Continue 信息。

不过如果用户有需求那么可以要求响应中携带 Continue 信息

在使用 URL 访问 Clusterepdia 时,响应的 Continue 可以作为下一次请求的 offset

搭配分页功能使用

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?withContinue=true&limit=1" | jq
{
  "kind": "DeploymentList",
  "apiVersion": "apps/v1",
  "metadata": {
    "continue": "1"
  },
  "items": [
    ...
  ]
}

在 kubectl 设置 search.clusterpedia.io/with-continue 会导致以分片拉取的形式拉取全量资源。

kubectl --cluster clusterpedia get deploy -l \
    "search.clusterpedia.io/with-continue=true"

响应携带剩余资源数量信息

在一些 UI 场景下,往往会需要获取到当前检索条件下的资源总量。

Kubernetes List 响应的 ListMeta 中存在 RemainingItemCount 字段,

通过复用该字段,便可在兼容 Kubernetes OpenAPI 的基础下计算出资源总量:

offset + len(list.items) + list.metadata.remainingItemCount

在 offset 过大时,remainingItemCount 可能为负数,保证总是可以计算出资源总量

URL Query 设置 withRemainingCount 即可要求响应携带剩余资源数量

搭配分页功能使用

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?withRemainingCount&limit=1" | jq
{
  "kind": "DeploymentList",
  "apiVersion": "apps/v1",
  "metadata": {
    "remainingItemCount": 23
  },
  "items": [
    ...
  ]
}

需要以 URL 的方式使用该功能

2 - 指定集群检索

Clusterpedia 除了支持多个集群的混合检索,还可以指定集群来检索资源。

在性能上使用 Search Label 或者 URL Query 来指定单个集群和在 URL Path 中指定集群并无区别

本文主要讲述在 URL Path 中指定集群

在以指定集群的方式使用 kubectl 前,需要先配置 kubectl 的集群快捷方式

kubectl --cluster cluster-1 get deployments -n kube-system
# 输出:
NAMESPACE     CLUSTER     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   cluster-1   coredns                   2/2     2            2           68d

将 cluster name 放到 URL 路径中来指定集群

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/clusters/cluster-1/apis/apps/v1/deployments"

也可以通过 URL Query 来指定单个集群

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/deployments?clusters=cluster-1"

指定集群支持的功能和多集群检索的作用基本相同,而且在 Owner 检索上更加方便, 另外在获取单个资源时也只能使用在 URL Path 中指定集群的方式

根据父辈或者祖辈 Owner 进行检索

Owner 查询必须指定单个集群,可以使用 Search Label 或者 URL Query 来指定,也可以在 URL Path 中指定集群名称

通过 Owenr UID 或者 Owner Name, 并且配合用于 Owner 辈分提升的 Owenr Senirority 可以完成基于祖辈 Owner 的资源检索。

关于具体的查询参数,可以参考 Owner 检索

通过这种方式,可以直接查询到 Deployment 相应的 Pods,无需查询有哪些 ReplicaSet 属于该 Deployment

指定 Owner 的 UID

在指定 Owenr UID 后,Owner NameOwenr Group Resource 会被忽略

首先使用 kubectl 获取 Deployment 的 UID

kubectl --cluster cluster-1 get deploy fake-deploy -o jsonpath="{.metadata.uid}"
#输出:
151ae265-28fe-4734-850e-b641266cd5da

在 kubectl 下获取 uid 可能比较麻烦,但是在 UI 场景中通常已经更容易查看 metadata.uid

使用 owner-uid 来指定 Owner 的 UID, owner-seniority 对 Owner 进行辈分提升。

owner-seniority 默认为 0,表示 Owner 为父辈。设置为 1,提升 Owenr 辈分成为祖父 Owenr

kubectl --cluster cluster-1 get pods -l \
    "search.clusterpedia.io/owner-uid=151ae265-28fe-4734-850e-b641266cd5da,\
     search.clusterpedia.io/owner-seniority=1"

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/clusters/cluster-1/api/v1/namespaces/default/pods?ownerUID=151ae265-28fe-4734-850e-b641266cd5da&ownerSeniority=1"

指定 Owner Name

如果事先并不知道 Owner 的 UID,那么指定 Owner UID 是一种比较麻烦的方式。

我们可以通过 Owner 的名字来指定 Owner,同时还可以指定 Owner Group Resource 来限制 Owner 的 Group Resource。

同样,我们以获取 Deployment 下相应的 Pods 来举例

kubectl --cluster cluster-1 get pods -l \
    "search.clusterpedia.io/owner-name=deploy-1,\
     search.clusterpedia.io/owner-seniority=1"

另外为了避免某些情况下,owner 资源存在多种类型,我们可以使用 Owner Group Resource 来限制 Owner 的类型

kubectl --cluster cluster-1 get pods -l \
    "search.clusterpedia.io/owner-name=deploy-1,\
     search.clusterpedia.io/owner-gr=deployments.apps,\
     search.clusterpedia.io/owner-seniority=1"

kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/clusters/cluster-1/api/v1/namespaces/default/pods?ownerName=deploy-1&ownerSeniority=1"

获取单个资源

当我们想要使用资源名称获取(Get)一个资源时,就必须要以 URL Path 的方式将集群名称传递进去,就像 namespace 一样。

如果使用多集群方式传递一个资源名称会报错

kubectl --cluster cluster-1 get deploy fake-deploy 
# 输出:
CLUSTER     NAME        READY   UP-TO-DATE   AVAILABLE   AGE
cluster-1   fake-deploy 1/1     1            1           35d

当然在 kubectl 中也可以通过 Search Label 来指定一个资源名称。

不过在 -o yaml 或者其他方式查看返回的源数据时,和使用 kubectl --cluster <cluster name> 是不一样的。

# 实际服务端返回 DeploymentList 的资源,由 kubectl 替换成 List 资源
kubectl --cluster clusterpedia get deploy -l 
    "search.clusterpedia.io/clusters=cluster-1,\
     search.clusterpedia.io/names=fake-deploy" -o yaml
# 输出:
apiVersion: v1
items:
- ...
kind: List
metadata:
  resourceVersion: ""
  selfLink: ""

实际返回的资源依然是一个 KindList,而 kubectl --cluster <clsuter name> 返回的便是具体的 Kind

kubectl --cluster cluster-1 get deploy fake-deploy -o yaml
# 输出:
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    deployment.kubernetes.io/revision: "1"
    shadow.clusterpedia.io/cluster-name: cluster-1
  creationTimestamp: "2021-12-16T02:26:29Z"
  generation: 2
  name: fake-deploy
  namespace: default
  resourceVersion: "38085769"
  uid: 151ae265-28fe-4734-850e-b641266cd5da
spec:
  ...
status:
  ...

获取指定资源的 URL 可以分为三部分

  • 资源检索前缀: /apis/clusterpedia.io/v1beta1/resources
  • 指定集群名称 /clusters/< cluster name >
  • 原生 Kubernetes API 的资源 Path /apis/apps/v1/namespaces/< namespace >/deployments/< resource name >
kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/clusters/cluster-1/apis/apps/v1/namespaces/default/deployments/fake-deploy"

3 - 聚合资源检索

关于聚合资源的概念可以查看 什么是聚合资源 (Collection Resource)

由于 kubectl 的限制,我们无法通过 Label Selector 或者其他方式来传递检索参数, 所以建议以 URL 的方式来检索聚合资源

请求聚合资源时,由于资源数量可能会非常大,一定要搭配分页功能使用。

kubectl get --raw="/apis/clusterpedia.io/v1beta1/collectionresources/workloads?limit=1" | jq
# 输出
{
  "kind": "CollectionResource",
  "apiVersion": "clusterpedia.io/v1beta1",
  "metadata": {
    "name": "workloads",
    "creationTimestamp": null
  },
  "resourceTypes": [
    {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment",
      "resource": "deployments"
    },
    {
      "group": "apps",
      "version": "v1",
      "resource": "daemonsets"
    },
    {
      "group": "apps",
      "version": "v1",
      "resource": "statefulsets"
    }
  ],
  "items": [
    {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      ...
    }
  ]
}

聚合资源的复杂检索和多集群资源检索 功能基本相同,只有部分操作不支持:

  • 不支持根据 Owner 检索,如果需要进行根据 Owner 检索需要指定具体的资源类型,可以参考 多集群检索指定集群检索
  • 不支持在 Collection Resource 中获取具体的单个资源,因为具体资源需要指定集群和资源类型,可以使用 获取单个资源

尽管 kubectl 无法很好的检索聚合资源,但是可以简单的体验一下。

由于无法传递分页以及其他检索条件,kubectl 会一次获取到所有的聚合资源,在接入了大量集群或者存在大量 deploymentsdaemonsetsstatefulsets 资源时,不要使用 kubectl 来查看聚合资源

kubectl get collectionresources workloads
# 输出
CLUSTER     GROUP   VERSION   KIND         NAMESPACE                     NAME                                          AGE
cluster-1   apps    v1        DaemonSet    kube-system                   vsphere-cloud-controller-manager              63d
cluster-2   apps    v1        Deployment   kube-system                   calico-kube-controllers                       109d
cluster-2   apps    v1        Deployment   kube-system                   coredns-coredns                               109d
...

请使用 URL 来检索聚合资源

Only Metadata

我们在检索 CollectionResource 时,获取到的资源默认是全量的资源信息,但是我们通常只需要获取资源的 metadata 即可。

在检索时我们可以使用 url query —— onlyMetadata 来只获取资源 Metadata。

$ kubectl get --raw "/apis/clusterpedia.io/v1beta1/collectionresources/workloads?onlyMetadata=true&limit=1" | jq
{
  "kind": "CollectionResource",
  "apiVersion": "clusterpedia.io/v1beta1",
  "metadata": {
    "name": "workloads",
    "creationTimestamp": null
  },
  "resourceTypes": [
    {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment",
      "resource": "deployments"
    }
  ],
  "items": [
    {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "annotations": {
          "deployment.kubernetes.io/revision": "1",
          "shadow.clusterpedia.io/cluster-name": "cluster-example"
        },
        "creationTimestamp": "2021-09-24T10:19:19Z",
        "generation": 1,
        "labels": {
          "k8s-app": "tigera-operator"
        },
        "name": "tigera-operator",
        "namespace": "tigera-operator",
        "resourceVersion": "125073610",
        "uid": "992f9d53-37cb-4184-a004-15b278b11f79"
      }
    }
  ]
}

Any CollectionResource

any collectionresource 是用户自由组合资源类型的方式之一,可以通过 自定义聚合资源 来查看更多。

clusterpedia 支持一种特殊的 CollectionResource —— any

$ kubectl get collectionresources
NAME            RESOURCES
any             *

在检索 any collectionresource 时,我们必须通过 url query 来指定一组资源类型,因此我们只能通过 clusterpedia-io/client-go 或者 url 来访问 any collectionresource

$ kubectl get collectionresources any
Error from server (BadRequest): url query - `groups` or `resources` is required

any collectionresource 支持两个 url query —— groupsresources

groupsresources 可以同时指定,当前是取两者并集,并且不会进行去重处理,由调用者负责去重,未来对该行为有一些优化。

$ kubectl get --raw "/apis/clusterpedia.io/v1beta1/collectionresources/any?onlyMetadata=true&groups=apps&resources=batch/jobs,batch/cronjobs" | jq

groups

groups 可以指定一组资源的组和版本,多个组版本使用 , 分隔,组版本格式为 < group >/< version >,也可以不指定版本 < group >对于 /api 下的资源,可以直接使用空字符串

示例:groups=apps/v1,,batch 指定了三个组 apps/v1, core, batch。

resources

resources 可以指定具体的资源类型,多个资源类型使用 , 分隔,资源类型格式为 < group >/< version >/< resource>,通过也可以不指定版本 < group >/< resource >

示例:resources=apps/v1/deployments,apps/daemonsets,/pods 指定了三种资源 deloyments,daemonsets 和 pods。