add some blogs

Signed-off-by: Iceber Gu <[email protected]>
klts-io · Jun 7, 2022 · 838af3a · 838af3a
1 parent 039aa08
commit 838af3a
Show file tree

Hide file tree

Showing 8 changed files with 985 additions and 0 deletions.
diff --git a/content/en/blog/clusterpedia-0.1.0.md b/content/en/blog/clusterpedia-0.1.0.md
@@ -0,0 +1,154 @@
+---
+title: Clusterpedia v0.1.0 Release — four important functions
+date: 2022-02-16
+---
+**This is the first release of** [**Clusterpedia**](https://clusterpedia.io) **🥳🥳🥳, and it also means that it is officially in the iteration phase.**
+
+Compared to the initial [v0.0.8](https://github.com/clusterpedia-io/clusterpedia/tree/v0.0.8) and [v0.0.9-alpha](https://github.com/clusterpedia-io/clusterpedia/tree/v0.0.9-alpha), v0.1.0 add a lot of features and makes some incompatible updates.
+
+>If upgrading from v0.0.9-alpha or v0.0.8, you can refer to [Upgrade to Clusterpedia 0.1.0](/blog/2022/02/15/upgrade-to-clusterpedia-0.1.0/)
+
+# Features Preview
+|Role|Search Label Key|URL Query|
+|:-|:-|:-|
+|Filter cluster names|`search.clusterpedia.io/clusters`|`clusters`|
+|Filter namespaces|`search.clusterpedia.io/namespaces`|`namespaces`|
+|Filter resource names|`search.clusterpedia.io/names`|`names`|
+|Specified Owner UID|`internalstorage.clusterpedia.io/owner-uid`|\-|
+|Specified Owner Seniority|`internalstorage.clusterpedia.io/owner-seniority`|`ownerSeniority`|
+|Order by fields|`search.clusterpedia.io/orderby`|`orderby`|
+|Set page size|`search.clusterpedia.io/size`|`limit`|
+|Set page offset|`search.clusterpedia.io/offset`|`continue`|
+|Response include Continue|`search.clusterpedia.io/with-continue`|`withContinue`|
+|Response include remaining count|`search.clusterpedia.io/with-remaining-count`|`withRemainingCount`|
+
+Native `Label Selector` and enhanced `Field Selector` supported in addition to search label.
+
+# Important Features
+Let's start with the more important features that have been added in 0.1.0
+
+* The number of remaining items carried in response data
+* Added warnning when searching for resources in a `Not Ready` cluster
+* Enhancements to the native FieldSelector
+* Search by Parent or Ancestor Owner
+
+## Warnning alert on resource search
+
+When a cluster is not ready for some reason, resources are often not synchronised properly either.
+
+Warnning alerts are used to alert users of cluster exceptions when searching for resources within the cluster, and the resources searched may not be accurate in real time.
+
+    $ kubectl get pediacluster
+    NAME        APISERVER                   VERSION   STATUS
+    cluster-1   https://10.6.100.10:6443    v1.22.2   ClusterSynchroStop
+
+    $ kubectl --cluster cluster-1 get pods
+    Warning: cluster-1 is not ready and the resources obtained may be inaccurate, reason: ClusterSynchroStop
+    CLUSTER     NAME                                                 READY   STATUS      RESTARTS   AGE
+    cluster-1   fake-pod-698dfbbd5b-64fsx                            1/1     Running     0          68d
+    cluster-1   fake-pod-698dfbbd5b-9ftzh                            1/1     Running     0          39d
+    cluster-1   fake-pod-698dfbbd5b-rk74p                            1/1     Running     0          39d
+    cluster-1   quickstart-ingress-nginx-admission-create--1-kxlnn   0/1     Completed   0          126d
+
+## Field Selector
+
+Native Kubernetes currently only supports field filtering on `metadata.name` and `metadata.namespace`, and the operators only support =, !=, ==\`, which is very limited.
+
+Although some specific resources will support some special fields, the use is still rather limited
+
+    # kubernetes/pkg
+    $ grep AddFieldLabelConversionFunc . -r
+    ./apis/core/v1/conversion.go:   err := scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Pod"),
+    ./apis/core/v1/conversion.go:   err = scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Node"),
+    ./apis/core/v1/conversion.go:   err = scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("ReplicationController"),
+    ./apis/core/v1/conversion.go:   return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Event"),
+    ./apis/core/v1/conversion.go:   return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Namespace"),
+    ./apis/core/v1/conversion.go:   return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Secret"),
+    ./apis/certificates/v1/conversion.go:   return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("CertificateSigningRequest"),
+    ./apis/certificates/v1beta1/conversion.go:      return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("CertificateSigningRequest"),
+    ./apis/batch/v1/conversion.go:  return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Job"),
+    ./apis/batch/v1beta1/conversion.go:             err = scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind(kind),
+    ./apis/events/v1/conversion.go: return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Event"),
+    ./apis/events/v1beta1/conversion.go:    return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Event"),
+    ./apis/apps/v1beta2/conversion.go:      if err := scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("StatefulSet"),
+    ./apis/apps/v1beta1/conversion.go:      if err := scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("StatefulSet"),
+
+Clusterpedia provides more powerful features based on the compatibility with existing Field Selector features, and supports the same operators as Label Selector: `!`, `=`, `!=`, `==`, `in`, `notin`.
+
+For example, we can filter by annotations, like label selector
+
+    kubectl get deploy --field-selector="metadata.annotations['test.io'] in (value1, value2)"
+
+[Lean More](https://clusterpedia.io/docs/usage/search/multi-cluster/#field-selector)
+
+## Search by Parent or Ancestor Owner
+
+There will usually be an Owner relationship between Kubernetes resources.
+
+    apiVersion: v1
+    kind: Pod
+    metadata:
+      ownerReferences:
+      - apiVersion: apps/v1
+        blockOwnerDeletion: true
+        controller: true
+        kind: ReplicaSet
+        name: fake-pod-698dfbbd5b
+        uid: d5bf2bdd-47d2-4932-84fb-98bde486d244
+
+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
+
+>Currently only supports query by Owner UID. The feature of using Owner Name for queries is still under discussion, we can join the discussion in the [issue: Support for searching resources by owner](https://github.com/clusterpedia-io/clusterpedia/issues/49)
+
+    $ DEPLOY_UID=$(kubectl --cluster cluster-1 get deploy fake-deploy -o jsonpath="{.metadata.uid}")
+    $ kubectl --cluster cluster-1 get pods -l \
+        "internalstorage.clusterpedia.io/owner-uid=$DEPLOY_UID,\
+         internalstorage.clusterpedia.io/owner-seniority=1"
+
+[Lean More](https://clusterpedia.io/docs/usage/search/multi-cluster/#search-by-parent-or-ancestor-owner)
+
+## The number of remaining items carried in response data
+
+**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](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ListMeta) of the Kubernetes List response.
+
+    type ListMeta struct {
+        ...
+
+            // remainingItemCount is the number of subsequent items in the list which are not included in this
+            // list response. If the list request contained label or field selectors, then the number of
+            // remaining items is unknown and the field will be left unset and omitted during serialization.
+            // If the list is complete (either because it is not chunking or because this is the last chunk),
+            // then there are no more remaining items and this field will be left unset and omitted during
+            // serialization.
+            // Servers older than v1.15 do not set this field.
+            // The intended use of the remainingItemCount is *estimating* the size of a collection. Clients
+            // should not rely on the remainingItemCount to be set or to be exact.
+            // +optional
+        RemainingItemCount *int64 `json:"remainingItemCount,omitempty" protobuf:"bytes,4,opt,name=remainingItemCount"`
+    }
+
+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**
+
+>Use with Paging
+
+    $ 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": [
+        ...
+      ]
+    }
+
+[Lean More](https://clusterpedia.io/docs/usage/search/multi-cluster/#response-with-remaining-count)
+
+# [Realease v0.1.0](https://github.com/clusterpedia-io/clusterpedia/releases/tag/v0.1.0)
diff --git a/content/en/blog/clusterpedia-0.2.0.md b/content/en/blog/clusterpedia-0.2.0.md
@@ -0,0 +1,178 @@
+---
+title: Clusterpedia v0.2.0 Release
+date: 2022-04-12
+---
+## Use helm to install
+
+Users can already use Helm to install Clusterpedia:
+
+    $ helm install clusterpedia . \
+      --namespace clusterpedia-system \
+      --create-namespace \
+      --set persistenceMatchNode={{ LOCAL_PV_NODE }} \
+      # --set installCRDs=true
+
+[Lean More](https://github.com/clusterpedia-io/clusterpedia/tree/main/charts)
+
+## Use the Kube Config to import a cluster
+
+For v0.1.0, users need to Configure the address for the imported cluster and the authentication information.
+
+    apiVersion: cluster.clusterpedia.io/v1alpha2
+    kind: PediaCluster
+    metadata:
+      name: cluster-example
+    spec:
+      apiserver: "https://10.30.43.43:6443"
+      caData:
+      tokenData:
+      certData:
+      keyData:
+      syncResources: []
+
+In v0.2.0, the `PediaCluster` added the `spec.kubeconfig` field so that users can use `kube config` to import the cluster directly.
+
+First you need to base64 encode the kube config for the imported cluster.
+
+    $ base64 ./kubeconfig.yaml
+
+Set the content after the base64 to PediaCluster `spec.kubeconfig`, in addition `spec.apiserver` and other authentication fields don’t need to set.
+
+    apiVersion: cluster.clusterpedia.io/v1alpha2
+    kind: PediaCluster
+    metadata:
+      name: cluster-example
+    spec:
+      kubeconfig: **base64 kubeconfig**
+      syncResources: []
+
+However, since the cluster address is configured in kube config, the **APIServer** is empty when you use kubectl get pediacluster.
+
+    $ kubectl get pediacluster
+    NAME              APISERVER   VERSION   STATUS
+    cluster-example               v1.22.2   Healthy
+
+Mutating addmission webhooks will be added in the future to automatically set `spec.apiserver`, currently if you want to show the cluster apiserver address when `kubectl get pediacluster`, then you need to manually configure the `spec.apiserver` field additionally.
+
+## New Search Feature
+
+### Search by creation time interval
+
+|Description|Search Label Key|URL Query|
+|:-|:-|:-|
+|Since|search.clusterpedia.io/since|since|
+|Before|search.clusterpedia.io/before|before|
+
+The creation time interval used for the search is left closed and right open, **since <= creation time < before**.
+
+There are four formats for creation time:
+
+1. `Unix Timestamp` for ease of use will distinguish between units of `s` or `ms` based on the length of the timestamp. The 10-bit timestamp is in seconds, the 13-bit timestamp is in milliseconds.
+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*
+
+>Because of the limitation of the kube label selector, the search label only supports `Unix Timestamp` and `UTC Date`.  
+>  
+>All formats are available using the url query method.
+
+Look at what resources are under the default namespace
+
+    $ kubectl --cluster clusterpedia get pods
+    CLUSTER           NAME                                                 READY   STATUS      RESTARTS       AGE
+    cluster-example   quickstart-ingress-nginx-admission-create--1-kxlnn   0/1     Completed   0              171d
+    cluster-example   fake-pod-698dfbbd5b-wvtvw                            1/1     Running     0              8d
+    cluster-example   fake-pod-698dfbbd5b-74cjx                            1/1     Running     0              21d
+    cluster-example   fake-pod-698dfbbd5b-tmcw7                            1/1     Running     0              8d
+
+We use the creation time to filter the resources.
+
+    $ kubectl --cluster clusterpedia get pods -l "search.clusterpedia.io/since=2022-03-20"
+    CLUSTER           NAME                        READY   STATUS    RESTARTS   AGE
+    cluster-example   fake-pod-698dfbbd5b-wvtvw   1/1     Running   0          8d
+    cluster-example   fake-pod-698dfbbd5b-tmcw7   1/1     Running   0          8d
+
+
+    $ kubectl --cluster clusterpedia get pods -l "search.clusterpedia.io/before=2022-03-20"
+    CLUSTER           NAME                                                 READY   STATUS      RESTARTS       AGE
+    cluster-example   quickstart-ingress-nginx-admission-create--1-kxlnn   0/1     Completed   0              171d
+    cluster-example   fake-pod-698dfbbd5b-74cjx                            1/1     Running     0              21d
+
+### Search by Owner Name
+
+As of v0.1.0, we can specify ancestor or parent `Owner UID` to query resources, but `Owner UID` is not convenient to use, after all, you still need to know the UID of the Owner resource in advance.
+
+In v0.2.0, we support querying directly with `Owner Name`, and the Owner query has been moved from experimental to released functionality, the prefix of **Search Label** has been upgraded from *internalstorage.c lusterpedia.io* to \*search.clusterpedia.io \*, and URL Query is provided.
+
+|Role|search label key|url query|
+|:-|:-|:-|
+|Specified Owner UID|search.clusterpedia.io/owner-uid|ownerUID|
+|Specified Owner Name|search.clusterpedia.io/owner-name|ownerName|
+|SPecified Owner Group Resource|search.clusterpedia.io/owner-gr|ownerGR|
+|Specified Owner Seniority|`internalstorage.clusterpedia.io/owner-seniority`|`ownerSeniority`|
+
+>Note that when specifying `Owner UID`, `Owner Name` and `Owner Group Resource` will be ignored.
+
+    $ kubectl --cluster cluster-example get pods -l \
+        "search.clusterpedia.io/owner-name=fake-pod, \
+         search.clusterpedia.io/owner-seniority=1"
+    CLUSTER           NAME                        READY   STATUS    RESTARTS   AGE
+    cluster-example   fake-pod-698dfbbd5b-wvtvw   1/1     Running   0          8d
+    cluster-example   fake-pod-698dfbbd5b-74cjx   1/1     Running   0          21d
+    cluster-example   fake-pod-698dfbbd5b-tmcw7   1/1     Running   0          8d
+
+**In addition, to avoid multiple types of owner resources in some cases, we can use the** `Owner Group Resource` **to restrict the type of owner.**
+
+    $ kubectl --cluster cluster-example get pods -l \
+        "search.clusterpedia.io/owner-name=fake-pod,\
+         search.clusterpedia.io/owner-gr=deployments.apps,\
+         search.clusterpedia.io/owner-seniority=1"
+    ... some output
+
+### Fuzzy Search base 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. |Role| search label key|url query| | -- | --------------- | ------- | |Fuzzy Search for resource name|internalstorage.clusterpedia.io/fuzzy-name|-|
+
+    $ kubectl --cluster clusterpedia get deployments -l "internalstorage.clusterpedia.io/fuzzy-name=fake"
+    CLUSTER           NAME       READY   UP-TO-DATE   AVAILABLE   AGE
+    cluster-example   fake-pod   3/3     3            3           113d
+
+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.
+
+## Other Features
+
+In v0.1.0, searching the resources allow the number of remaining resources to be returned so that the user can calculate the total number of resources.
+
+This feature has been enhanced in v0.2.0. When offset is too large, `remainingItemCount` may be negative, ensuring that the total number of resources can always be calculated.
+
+[Lean More](https://clusterpedia.io/docs/usage/search/multi-cluster/#response-with-remaining-count)
+
+## [Release Notes](https://github.com/clusterpedia-io/clusterpedia/releases)
+
+* Support of using Helm Charts for installation ([\#53](https://github.com/clusterpedia-io/clusterpedia/pull/53), [\#125](https://github.com/clusterpedia-io/clusterpedia/pull/125), @calvin0327, @wzshiming)
+* `PediaCluster` supports for importing a cluster using the kubeconfig ([\#115](https://github.com/clusterpedia-io/clusterpedia/pull/115), @wzshiming)
+
+### APIServer
+
+* Support for filtering resources by a period of creation ([\#113](https://github.com/clusterpedia-io/clusterpedia/pull/113), @cleverhu)
+* Support for searching for resources by an Owner name. Now, the feature of `Search by Owner` is officially released. ([\#91](https://github.com/clusterpedia-io/clusterpedia/pull/91), @Iceber)
+
+### Default Storage Layer
+
+* Support for fuzzy search by a resource name ([\#117](https://github.com/clusterpedia-io/clusterpedia/pull/117), @cleverhu)
+* `RemainingItemCount` can be a negative number. We can still use `offset + len(items) + remainingItemCount` to calculate the total amount of resources if the `Offset` is too large. ([\#123](https://github.com/clusterpedia-io/clusterpedia/pull/123), @cleverhu)
+
+### Bug Fixes
+
+* Fixed unnecessary `json.Unmarshal` and improved performance when searching ([\#89](https://github.com/clusterpedia-io/clusterpedia/pull/89), [\#92](https://github.com/clusterpedia-io/clusterpedia/pull/92), @Iceber)
+
+### Deprecation
+
+* `Search by Owner` has been released as an official feature. `internalstorage.clusterpedia.io/owner-name` and `internalstorage.clusterpedia.io/owner-seniority` will be removed in the next release. ([\#91](https://github.com/clusterpedia-io/clusterpedia/pull/91), @Iceber)
+
+### Other
+
+* `golangci-lint` is used as a static checking tool ([\#86](https://github.com/clusterpedia-io/clusterpedia/pull/86), [\#88](https://github.com/clusterpedia-io/clusterpedia/pull/88), @Iceber)
+* Added CI Workloads such as static checking and unit testing for code [\#87](https://github.com/clusterpedia-io/clusterpedia/pull/87), @Iceber)