资源检索

• 1: 多集群检索
• 2: 指定集群检索
• 3: 聚合资源检索

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 根据所有集群同步的资源来提供多集群的资源检索，可以查看 同步集群资源 来更新需要同步的资源

基本功能

指定集群

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

• kubectl
• URL

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

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

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

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

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

指定命名空间

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

• kubectl
• URL

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

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

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"

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

• kubectl
• URL

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

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

指定资源名称

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

• kubectl
• URL

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

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"

创建时间的区间

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

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

• kubectl
• URL

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

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.name 和 metadata.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 进行检索

分页与排序

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

根据多个字段进行排序

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

当前默认存储层支持对 cluster，namespace，name，created_at，resource_version 进行正序和倒序的排序，字段也支持随意的组合

• kubectl
• URL

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

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

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

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

分页

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

Clusterpedia 复用 ListOptions.Limit 和 ListOptions.Continue 字段作为分页的 size 和 offset。

• kubectl
• URL

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

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

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
• kubectl

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 --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
• kubectl

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": [
    ...
  ]
}

2 - 指定集群检索

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

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

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

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

• kubectl
• URL

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

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

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 Name 和 Owenr 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

• kubectl
• URL

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
• URL

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

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
• URL

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

# 实际服务端返回 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: ""

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:
  ...

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 的方式来检索聚合资源。

• URL
• kubectl

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",
      ...
    }
  ]
}

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
...

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 —— groups 和 resources

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

$ 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。