Search

• 1: Multiple Clusters
• 2: Specified a Cluster
• 3: Collection Resource

1 - Multiple Clusters

Multi-cluster resource search allows us to filter resources in multiple clusters at once based on query criteria, and provides the ability to paginate and sort these resources.

When using kubectl, we can see what resources are currently available for search

kubectl --cluster clusterpedia api-resources

# Output：
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 provides multi-cluster resource search based on all cluster-synchronized resources, and we can view Sync Cluster Resources to update the resources that need to be synchronized.

Basic Features

Specify Clusters

When searching multiple clusters, all clusters will be retrieved by default, we can also specify a single cluster or a group of clusters

• kubectl
• URL

kubectl --cluster clusterpedia get deployments -l "search.clusterpedia.io/clusters in (cluster-1,cluster-2)"

# Output：
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

# specifying a single cluster
kubectl --cluster clusterpedia get deployments -l "search.clusterpedia.io/clusters=cluster-1"

# specifying a cluster can also be done with --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"

Specify Namespaces

We can specify a single namespace or all namespaces as if we were viewing a native Kubernetes resource.

• kubectl
• URL

kubectl --cluster clusterpedia get deployments -n kube-system

# Output：
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

# Output：
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"

# Specify namespace
kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/namespaces/kube-system/deployments"

In addition to specifying a single namespace, we can also specify to search the resources under a group of namespaces.

• kubectl
• URL

kubectl --cluster clusterpedia get deployments -A -l "search.clusterpedia.io/namespaces in (kube-system, default)"

# Output：
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"

Specify Resource Names

Users can filter resources by a group of resource names

• kubectl
• URL

kubectl --cluster clusterpedia get deployments -A -l "search.clusterpedia.io/names=coredns"

# Output:
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"

# search resources with specified names under default namespace
kubectl get --raw="/apis/clusterpedia.io/v1beta1/resources/apis/apps/v1/namespaces/default/deployments?names=kube-coredns,dd-airflow-web"

Creation Time Interval

The creation time interval used for the search is left closed and right open, since <= creation time < before.

For more details on the time interval parameters, see Search by Creation Time Interval

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

Fuzzy Search

Currently supports fuzzy search based on resource names.

Since fuzzy search needs to be discussed further, it is temporarily provided as an experimental feature.

Only the Search Label method is supported, URL Query isn’t supported.

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

Filters out deployments whose names contain the test string.

You can use the in operator to pass multiple fuzzy arguments, so that you can filter out resources that have all strings in their names.

Field Selector

Native Kubernetes currently only supports field filtering on metadata.name and metadata.namespace, and the operators only support =, !=, ==`, which is very limited.

Clusterpedia provides more powerful features based on the compatibility with existing Field Selector features, and supports the same operators as Label Selector.

Field Selector’s key currently supports three formats.

• Use . to sperate fields

kubectl --cluster clusterpedia get pods --field-selector="status.phase=Running"

# we can also add the first character `.`
kubectl --cluster clusterpedia get pods --field-selector=".status.phase notin (Running,Succeeded)"

• Field names wrapped in '' or "" can be used for fields with illegal characters like .

kubectl --cluster clusterpedia get deploy \
    --field-selector="metadata.annotations['test.io'] in (value1,value2),spec.replica=3"

• Use [] to separate fields, the string inside [] must be wrapped with '' or ""

kubectl --cluster clusterpedia get pods --field-selector="status['phase']!=Running"

Support List Fields

The actual design of field filtering takes into account the filtering of fields within list elements, but more discussion is needed as to whether the usage scenario actually makes sense: issue: support list field filtering

Examples：

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)"

Search by Parent or Ancestor Owner

Searching by Owner is a very useful search function, and Clusterpedia also supports the seniority advancement of Owner to search for grandparents and even higher seniority.

By searching by Owner, we can query all Pods under Deployment at once, without having to query ReplicaSet in between.

When using the Owner query, we must specify a single cluster, either as a Serach Label or URL Query, or you can specify the cluster name in the URL Path.

For details on how to search by Owner, you can refer to Search by Parent or Ancestor Owenr within a specified cluster

Paging and Sorting

Paging and sorting are essential features for resource retrieval.

Sorting by multiple fields

Multiple fields can be specified for sorting, and the support for sorting fields is determined by the Storage Layer.

The current Default Storage Layer supports sorting cluster，namespace，name，created_at，resource_version in both asc and desc, and the fields are also supported in any combination

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

Paging

Native Kubernetes actually supports paging, and fields for paging queries already exist in ListOptions.

Clusterpedia reuses the ListOptions.Limit and ListOptions.Continue fields as the size and offset for paging.

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

Response With Continue

ListMeta.Continue can be used in ListOptions.Continue as the offset for the next request.

As mentioned in the paging feature, Clusterepdia does not have continue in the response to prevent kubectl from pulling the full amount of data in pieces.

However, if the user requires it, he can request that the response include 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"

Response With Remaining Count

In some UI cases, it is often necessary to get the total number of resources in the current search condition.

The RemainingItemCount field exists in the ListMeta of the Kubernetes List response.

By reusing this field, the total number of resources can be returned in a Kubernetes OpenAPI-compatible manner:

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

When offset is too large, remainingItemCount may be negative, ensuring that the total number of resources can always be calculated.

• 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 - Specified a Cluster

In addition to searching in multiple clusters, Clusterpedia can also search for resources in a specified cluster.

Using Search Label or URL Query to specify a single cluster is not different from specifying a cluster in URL Path in terms of performance

This topic focuses on specifying clusters in URL Path

Before using kubectl in the way of specifying a cluster, you need to configure the cluster shortcut for kubectl

• kubectl
• URL

kubectl --cluster cluster-1 get deployments -n kube-system

# Output:
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"

The function supported by searching in a specified cluster is basically the same as that of multi-cluster search.

It is more convenient for searching by Owner in a specified cluster. In addition, when getting a single resource, you can only use the specified cluster in the URL Path.

Search by Parent or Ancestor Owner

To query by Owner, you shall specify a single cluster. You can use Search Label or URL Query to specify, or specify the cluster name in the URL Path.

Searching for resources based on ancestor owners can be done with Owner UID or Owner Name, and with Owner Seniority for Owner seniority advancement.

For the specific query parameters, you can refer to Search by Owner

In this way, you can directly search for the Pods corresponding to a Deployment without having to query which ReplicaSet belong to that Deployment.

Use the Owner UID

Owner Name and Owner Group Resource will be ignored after Owner UID is specified.

Firstly use kubectl to get Deployment UID

kubectl --cluster cluster-1 get deploy fake-deploy -o jsonpath="{.metadata.uid}"

#Output:
151ae265-28fe-4734-850e-b641266cd5da

Getting the uid under kubectl may be tricky, but it’s usually already easier to check metadata.uid in UI scenarios

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

Use the Owner Name

If the Owner UID is not known in advance, then using Owner UID is a more troublesome way.

We can specify the Owner by it’s name, and we can also specify Owner Group Resource to restrict the Owner’s Group Resource.

Again, let’s take the example of getting the corresponding Pods under Deployment.

• 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 a single resource

When we want to use the resource name to get (Get) a resource, we must pass the cluster name in the URL Path, just like namespace.

• kubectl
• URL

kubectl --cluster cluster-1 get deploy fake-deploy 

# Output:
CLUSTER     NAME        READY   UP-TO-DATE   AVAILABLE   AGE
cluster-1   fake-deploy 1/1     1            1           35d

# The actual server returns the DeploymentList resource, which is replaced with a list by kubectl
kubectl --cluster clusterpedia get deploy -l 
    "search.clusterpedia.io/clusters=cluster-1,\
     search.clusterpedia.io/names=fake-deploy" -o yaml

# Output:
apiVersion: v1
items:
- ...
kind: List
metadata:
  resourceVersion: ""
  selfLink: ""

kubectl --cluster cluster-1 get deploy fake-deploy -o yaml

# Output:
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

For collection resource, refer to What is Collection Resource

Due to the limitation of kubectl, we cannot pass search conditions through Label Selector or other methods, so it is recommended to search for Collection Resource by using a URL.

• URL
• kubectl

kubectl get --raw="/apis/clusterpedia.io/v1beta1/collectionresources/workloads?limit=1" | jq

# Output
{
  "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

# Output
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

When we retrieve a CollectionResource, the default resource is the full resource content, but sometimes we just need to retrieve the metadata of the resource.

We can use url query – onlyMetadata to retrieve only the resource metadata when retrieving.

$ 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 is one of the ways that users can freely combine resource types with custom collection resources to see more.

clusterpedia supports a special CollectionResource —— any.

$ kubectl get collectionresources
NAME            RESOURCES
any             *

When retrieving any collectionresource, we must specify a set of resource types by url query, so we can only retrieve any collectionresource via clusterpedia-io/client-go or URL.

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

any collectionresource supports two url queries —— groups and resources

groups and resources can be specified together, currently they are taken together and are not de-duplicated, the caller is responsible for de-duplication, there are some future optimizations for this behavior.

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

groups

groups can specify a group and version of a set of resources, with multiple group versions separated by ,,

the group version format is < group >/< version >, or no version can be specified < group >, for resources under /api, you can just use the empty string.

Example: groups=apps/v1,,batch specifies three groups apps/v1, core, batch.

resources

resources can specify a specific resource type, multiple resource types are separated by ,,

the resource type format is < group >/< version >/< resource>, by also not specifying the version < group >/< resource >.

Example: resources=apps/v1/deployments,apps/daemonsets,/pods specifies three resources deloyments, daemonsets and pods.