From 47db5116f2f764f9dc94f01f8592032e396d6539 Mon Sep 17 00:00:00 2001 From: Rudro-25 Date: Wed, 23 Oct 2024 17:21:21 +0600 Subject: [PATCH] Add Zookeeper Ops Docs (restart, version-upgrade) --- docs/examples/zookeeper/restart/ops.yaml | 11 + .../examples/zookeeper/restart/zookeeper.yaml | 17 ++ .../zk-version-upgrade-ops.yaml | 13 + .../zookeeper/update-version/zookeeper.yaml | 17 ++ docs/guides/zookeeper/concepts/opsrequest.md | 60 ++-- docs/guides/zookeeper/restart/_index.md | 10 + docs/guides/zookeeper/restart/restart.md | 208 +++++++++++++ .../guides/zookeeper/update-version/_index.md | 10 + .../zookeeper/update-version/overview.md | 54 ++++ .../update-version/update-version.md | 275 ++++++++++++++++++ .../zookeeper/zk-version-update.svg | 4 + 11 files changed, 649 insertions(+), 30 deletions(-) create mode 100644 docs/examples/zookeeper/restart/ops.yaml create mode 100644 docs/examples/zookeeper/restart/zookeeper.yaml create mode 100644 docs/examples/zookeeper/update-version/zk-version-upgrade-ops.yaml create mode 100644 docs/examples/zookeeper/update-version/zookeeper.yaml create mode 100644 docs/guides/zookeeper/restart/_index.md create mode 100644 docs/guides/zookeeper/restart/restart.md create mode 100644 docs/guides/zookeeper/update-version/_index.md create mode 100644 docs/guides/zookeeper/update-version/overview.md create mode 100644 docs/guides/zookeeper/update-version/update-version.md create mode 100644 docs/images/day-2-operation/zookeeper/zk-version-update.svg diff --git a/docs/examples/zookeeper/restart/ops.yaml b/docs/examples/zookeeper/restart/ops.yaml new file mode 100644 index 000000000..b062d4725 --- /dev/null +++ b/docs/examples/zookeeper/restart/ops.yaml @@ -0,0 +1,11 @@ +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: zk-restart + namespace: demo +spec: + type: Restart + databaseRef: + name: zk-quickstart + timeout: 3m + apply: Always \ No newline at end of file diff --git a/docs/examples/zookeeper/restart/zookeeper.yaml b/docs/examples/zookeeper/restart/zookeeper.yaml new file mode 100644 index 000000000..7e8f26ca6 --- /dev/null +++ b/docs/examples/zookeeper/restart/zookeeper.yaml @@ -0,0 +1,17 @@ +apiVersion: kubedb.com/v1alpha2 +kind: ZooKeeper +metadata: + name: zk-quickstart + namespace: demo +spec: + version: "3.8.3" + adminServerPort: 8080 + replicas: 3 + storage: + resources: + requests: + storage: "1Gi" + storageClassName: "standard" + accessModes: + - ReadWriteOnce + deletionPolicy: "WipeOut" \ No newline at end of file diff --git a/docs/examples/zookeeper/update-version/zk-version-upgrade-ops.yaml b/docs/examples/zookeeper/update-version/zk-version-upgrade-ops.yaml new file mode 100644 index 000000000..f6424dbb1 --- /dev/null +++ b/docs/examples/zookeeper/update-version/zk-version-upgrade-ops.yaml @@ -0,0 +1,13 @@ +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: upgrade-topology + namespace: demo +spec: + databaseRef: + name: zk-quickstart + type: UpdateVersion + updateVersion: + targetVersion: 3.9.1 + timeout: 5m + apply: IfReady diff --git a/docs/examples/zookeeper/update-version/zookeeper.yaml b/docs/examples/zookeeper/update-version/zookeeper.yaml new file mode 100644 index 000000000..7e8f26ca6 --- /dev/null +++ b/docs/examples/zookeeper/update-version/zookeeper.yaml @@ -0,0 +1,17 @@ +apiVersion: kubedb.com/v1alpha2 +kind: ZooKeeper +metadata: + name: zk-quickstart + namespace: demo +spec: + version: "3.8.3" + adminServerPort: 8080 + replicas: 3 + storage: + resources: + requests: + storage: "1Gi" + storageClassName: "standard" + accessModes: + - ReadWriteOnce + deletionPolicy: "WipeOut" \ No newline at end of file diff --git a/docs/guides/zookeeper/concepts/opsrequest.md b/docs/guides/zookeeper/concepts/opsrequest.md index 776f5edbc..51d2ec5f7 100644 --- a/docs/guides/zookeeper/concepts/opsrequest.md +++ b/docs/guides/zookeeper/concepts/opsrequest.md @@ -1,9 +1,9 @@ --- -title: ZooKeeperOpsRequests CRD +title: ZooKeeperOpsRequest CRD menu: docs_{{ .version }}: identifier: zk-opsrequest - name: ZooKeeperOpsRequests + name: ZooKeeperOpsRequest parent: zk-concepts-zookeeper weight: 25 menu_name: docs_{{ .version }} @@ -12,19 +12,19 @@ section_menu_id: guides > New to KubeDB? Please start [here](/docs/README.md). -# ZooKeeperOpsRequests +# ZooKeeperOpsRequest -## What is ZooKeeperOpsRequests +## What is ZooKeeperOpsRequest -`ZooKeeperOpsRequests` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration for [ZooKeeper](https://zookeeper.apache.org/) administrative operations like database version updating, horizontal scaling, vertical scaling etc. in a Kubernetes native way. +`ZooKeeperOpsRequest` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration for [ZooKeeper](https://zookeeper.apache.org/) administrative operations like database version updating, horizontal scaling, vertical scaling etc. in a Kubernetes native way. -## ZooKeeperOpsRequests CRD Specifications +## ZooKeeperOpsRequest CRD Specifications -Like any official Kubernetes resource, a `ZooKeeperOpsRequests` has `TypeMeta`, `ObjectMeta`, `Spec` and `Status` sections. +Like any official Kubernetes resource, a `ZooKeeperOpsRequest` has `TypeMeta`, `ObjectMeta`, `Spec` and `Status` sections. -Here, some sample `ZooKeeperOpsRequests` CRs for different administrative operations is given below: +Here, some sample `ZooKeeperOpsRequest` CRs for different administrative operations is given below: -**Sample `ZooKeeperOpsRequests` for updating database:** +**Sample `ZooKeeperOpsRequest` for updating database:** Let's assume that you have a KubeDB managed ZooKeeper cluster named `zk-quickstart` running on your kubernetes with version `3.8.3`. Now, You can update it's version to `3.9.1` using the following manifest. @@ -42,7 +42,7 @@ spec: targetVersion: 3.9.1 ``` -**Sample `ZooKeeperOpsRequests` Objects for Horizontal Scaling of the database Cluster:** +**Sample `ZooKeeperOpsRequest` Objects for Horizontal Scaling of the database Cluster:** You can scale up and down your zookeeper cluster horizontally. ```yaml @@ -59,13 +59,13 @@ spec: replicas: 5 ``` -**Sample `ZooKeeperOpsRequests` Objects for Vertical Scaling of the database cluster:** +**Sample `ZooKeeperOpsRequest` Objects for Vertical Scaling of the database cluster:** You can vertically scale up or down your cluster by updating the requested cpu, memory or, by limiting them. ```yaml apiVersion: ops.kubedb.com/v1alpha1 -kind: ZooKeeperOpsRequests +kind: ZooKeeperOpsRequest metadata: name: zookeeper-vscale namespace: demo @@ -84,7 +84,7 @@ spec: memory: 2Gi ``` -**Sample `ZooKeeperOpsRequests` Objects for Reconfiguring database cluster:** +**Sample `ZooKeeperOpsRequest` Objects for Reconfiguring database cluster:** Reconfigure your cluster by applying new configuration via `zoo.conf` file. @@ -137,7 +137,7 @@ spec: name: new-config-secret ``` -**Sample `ZooKeeperOpsRequests` Objects for Volume Expansion of database cluster:** +**Sample `ZooKeeperOpsRequest` Objects for Volume Expansion of database cluster:** You can expand ZooKeeper storage volume in both online and offline mode. @@ -171,7 +171,7 @@ spec: node: 4Gi ``` -**Sample `ZooKeeperOpsRequests` Objects for Reconfiguring TLS of the database:** +**Sample `ZooKeeperOpsRequest` Objects for Reconfiguring TLS of the database:** You can use this Ops-Request to Add, Update, Remove or Rotate Your certificates used in TLS connectivity. @@ -220,9 +220,9 @@ spec: remove: true ``` -Here, we are going to describe the various sections of a `ZooKeeperOpsRequests` crd. +Here, we are going to describe the various sections of a `ZooKeeperOpsRequest` crd. -A `ZooKeeperOpsRequests` object has the following fields in the `spec` section. +A `ZooKeeperOpsRequest` object has the following fields in the `spec` section. ### spec.databaseRef @@ -232,7 +232,7 @@ A `ZooKeeperOpsRequests` object has the following fields in the `spec` section. ### spec.type -`spec.type` specifies the kind of operation that will be applied to the database. Currently, the following types of operations are allowed in `ZooKeeperOpsRequests`. +`spec.type` specifies the kind of operation that will be applied to the database. Currently, the following types of operations are allowed in `ZooKeeperOpsRequest`. - `Upgrade` / `UpdateVersion` - `HorizontalScaling` @@ -242,7 +242,7 @@ A `ZooKeeperOpsRequests` object has the following fields in the `spec` section. - `ReconfigureTLS` - `Restart` -> You can perform only one type of operation on a single `ZooKeeperOpsRequests` CR. For example, if you want to update your database and scale up its replica then you have to create two separate `ZooKeeperOpsRequests`. At first, you have to create a `ZooKeeperOpsRequests` for updating. Once it is completed, then you can create another `ZooKeeperOpsRequests` for scaling. +> You can perform only one type of operation on a single `ZooKeeperOpsRequest` CR. For example, if you want to update your database and scale up its replica then you have to create two separate `ZooKeeperOpsRequest`. At first, you have to create a `ZooKeeperOpsRequest` for updating. Once it is completed, then you can create another `ZooKeeperOpsRequest` for scaling. > Note: There is an exception to the above statement. It is possible to specify both `spec.configuration` & `spec.verticalScaling` in a OpsRequest of type `VerticalScaling`. @@ -338,33 +338,33 @@ This field controls the execution of obsRequest depending on the database state. Use IfReady, if you want to process the opsRequest only when the database is Ready. And use Always, if you want to process the execution of opsReq irrespective of the Database state. -### ZooKeeperOpsRequests `Status` +### ZooKeeperOpsRequest `Status` -`.status` describes the current state and progress of a `ZooKeeperOpsRequests` operation. It has the following fields: +`.status` describes the current state and progress of a `ZooKeeperOpsRequest` operation. It has the following fields: ### status.phase -`status.phase` indicates the overall phase of the operation for this `ZooKeeperOpsRequests`. It can have the following three values: +`status.phase` indicates the overall phase of the operation for this `ZooKeeperOpsRequest`. It can have the following three values: | Phase | Meaning | |-------------|-------------------------------------------------------------------------------------| -| Successful | KubeDB has successfully performed the operation requested in the ZooKeeperOpsRequests | -| Progressing | KubeDB has started the execution of the applied ZooKeeperOpsRequests | -| Failed | KubeDB has failed the operation requested in the ZooKeeperOpsRequests | -| Denied | KubeDB has denied the operation requested in the ZooKeeperOpsRequests | -| Skipped | KubeDB has skipped the operation requested in the ZooKeeperOpsRequests | +| Successful | KubeDB has successfully performed the operation requested in the ZooKeeperOpsRequest | +| Progressing | KubeDB has started the execution of the applied ZooKeeperOpsRequest | +| Failed | KubeDB has failed the operation requested in the ZooKeeperOpsRequest | +| Denied | KubeDB has denied the operation requested in the ZooKeeperOpsRequest | +| Skipped | KubeDB has skipped the operation requested in the ZooKeeperOpsRequest | Important: Ops-manager Operator can skip an opsRequest, only if its execution has not been started yet & there is a newer opsRequest applied in the cluster. `spec.type` has to be same as the skipped one, in this case. ### status.observedGeneration -`status.observedGeneration` shows the most recent generation observed by the `ZooKeeperOpsRequests` controller. +`status.observedGeneration` shows the most recent generation observed by the `ZooKeeperOpsRequest` controller. ### status.conditions -`status.conditions` is an array that specifies the conditions of different steps of `ZooKeeperOpsRequests` processing. Each condition entry has the following fields: +`status.conditions` is an array that specifies the conditions of different steps of `ZooKeeperOpsRequest` processing. Each condition entry has the following fields: -- `types` specifies the type of the condition. ZooKeeperOpsRequests has the following types of conditions: +- `types` specifies the type of the condition. ZooKeeperOpsRequest has the following types of conditions: | Type | | Meaning | |--------------------------------|---|---------------------------------------------------------------------------| diff --git a/docs/guides/zookeeper/restart/_index.md b/docs/guides/zookeeper/restart/_index.md new file mode 100644 index 000000000..ef714be39 --- /dev/null +++ b/docs/guides/zookeeper/restart/_index.md @@ -0,0 +1,10 @@ +--- +title: Restart ZooKeeper +menu: + docs_{{ .version }}: + identifier: zk-restart + name: Restart + parent: zk-zookeeper-guides + weight: 100 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/zookeeper/restart/restart.md b/docs/guides/zookeeper/restart/restart.md new file mode 100644 index 000000000..502452d2a --- /dev/null +++ b/docs/guides/zookeeper/restart/restart.md @@ -0,0 +1,208 @@ +--- +title: Restart ZooKeeper +menu: + docs_{{ .version }}: + identifier: zk-restart-details + name: Restart Cluster + parent: zk-restart + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Restart ZooKeeper + +KubeDB supports restarting the ZooKeeper database via a ZooKeeperOpsRequest. Restarting is useful if some pods are got stuck in some phase, or they are not working correctly. This tutorial will show you how to use that. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/zookeeper](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/zookeeper) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Deploy ZooKeeper + +In this section, we are going to deploy a ZooKeeper database using KubeDB. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: ZooKeeper +metadata: + name: zk-quickstart + namespace: demo +spec: + version: "3.8.3" + adminServerPort: 8080 + replicas: 3 + storage: + resources: + requests: + storage: "1Gi" + storageClassName: "standard" + accessModes: + - ReadWriteOnce + deletionPolicy: "WipeOut" + +``` + +Let's create the `ZooKeeper` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/zookeeper/restart/zookeeper.yaml +zookeeper.kubedb.com/zk-quickstart created +``` + +## Apply Restart opsRequest + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: zk-restart + namespace: demo +spec: + type: Restart + databaseRef: + name: zk-quickstart + timeout: 3m + apply: Always +``` + +- `spec.type` specifies the Type of the ops Request +- `spec.databaseRef` holds the name of the ZooKeeper database. The db should be available in the same namespace as the opsRequest +- The meaning of `spec.timeout` & `spec.apply` fields will be found [here](/docs/guides/zookeeper/concepts/opsrequest.md#spectimeout) + +> Note: The method of restarting the standalone & clustered zookeeper is exactly same as above. All you need, is to specify the corresponding ZooKeeper name in `spec.databaseRef.name` section. + +Let's create the `ZooKeeperOpsRequest` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/zookeeper/restart/ops.yaml +zookeeperopsrequest.ops.kubedb.com/zk-restart created +``` + +Now the Ops-manager operator will restart the pods sequentially by their cardinal suffix. + +```shell +$ kubectl get zookeeperopsrequest -n demo +NAME TYPE STATUS AGE +restart Restart Successful 10m + +$ kubectl get zookeeperopsrequest -n demo -oyaml zk-restart +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: | + {"apiVersion":"ops.kubedb.com/v1alpha1","kind":"ZooKeeperOpsRequest","metadata":{"annotations":{},"name":"zk-restart","namespace":"demo"},"spec":{"apply":"Always","databaseRef":{"name":"zk-quickstart"},"timeout":"3m","type":"Restart"}} + creationTimestamp: "2024-10-22T09:22:57Z" + generation: 1 + name: zk-restart + namespace: demo + resourceVersion: "1072309" + uid: 6091d9fa-1c2b-4734-bdd1-1ace91460bea +spec: + apply: Always + databaseRef: + name: zk-quickstart + timeout: 3m + type: Restart +status: + conditions: + - lastTransitionTime: "2024-10-22T09:22:57Z" + message: ZooKeeper ops-request has started to restart zookeeper nodes + observedGeneration: 1 + reason: Restart + status: "True" + type: Restart + - lastTransitionTime: "2024-10-22T09:25:45Z" + message: Successfully Restarted ZooKeeper nodes + observedGeneration: 1 + reason: RestartNodes + status: "True" + type: RestartNodes + - lastTransitionTime: "2024-10-22T09:23:05Z" + message: get pod; ConditionStatus:True; PodName:zk-quickstart-0 + observedGeneration: 1 + status: "True" + type: GetPod--zk-quickstart-0 + - lastTransitionTime: "2024-10-22T09:23:05Z" + message: evict pod; ConditionStatus:True; PodName:zk-quickstart-0 + observedGeneration: 1 + status: "True" + type: EvictPod--zk-quickstart-0 + - lastTransitionTime: "2024-10-22T09:23:10Z" + message: running pod; ConditionStatus:False + observedGeneration: 1 + status: "False" + type: RunningPod + - lastTransitionTime: "2024-10-22T09:23:45Z" + message: get pod; ConditionStatus:True; PodName:zk-quickstart-1 + observedGeneration: 1 + status: "True" + type: GetPod--zk-quickstart-1 + - lastTransitionTime: "2024-10-22T09:23:45Z" + message: evict pod; ConditionStatus:True; PodName:zk-quickstart-1 + observedGeneration: 1 + status: "True" + type: EvictPod--zk-quickstart-1 + - lastTransitionTime: "2024-10-22T09:24:25Z" + message: get pod; ConditionStatus:True; PodName:zk-quickstart-2 + observedGeneration: 1 + status: "True" + type: GetPod--zk-quickstart-2 + - lastTransitionTime: "2024-10-22T09:24:25Z" + message: evict pod; ConditionStatus:True; PodName:zk-quickstart-2 + observedGeneration: 1 + status: "True" + type: EvictPod--zk-quickstart-2 + - lastTransitionTime: "2024-10-22T09:25:05Z" + message: get pod; ConditionStatus:True; PodName:zk-quickstart-3 + observedGeneration: 1 + status: "True" + type: GetPod--zk-quickstart-3 + - lastTransitionTime: "2024-10-22T09:25:05Z" + message: evict pod; ConditionStatus:True; PodName:zk-quickstart-3 + observedGeneration: 1 + status: "True" + type: EvictPod--zk-quickstart-3 + - lastTransitionTime: "2024-10-22T09:25:45Z" + message: Controller has successfully restart the ZooKeeper replicas + observedGeneration: 1 + reason: Successful + status: "True" + type: Successful + observedGeneration: 1 + phase: Successful + +``` + + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete zookeeperopsrequest -n demo zk-restart +kubectl delete zookeeper -n demo zk-quickstart +kubectl delete ns demo +``` + +## Next Steps + +- Detail concepts of [ZooKeeper object](/docs/guides/zookeeper/concepts/zookeeper.md). +- Monitor your ZooKeeper database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/zookeeper/monitoring/using-prometheus-operator.md). +- Monitor your ZooKeeper database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/zookeeper/monitoring/using-builtin-prometheus.md). +- Detail concepts of [ZooKeeper object](/docs/guides/zookeeper/concepts/zookeeper.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/zookeeper/update-version/_index.md b/docs/guides/zookeeper/update-version/_index.md new file mode 100644 index 000000000..4a6be3d8d --- /dev/null +++ b/docs/guides/zookeeper/update-version/_index.md @@ -0,0 +1,10 @@ +--- +title: Updating ZooKeeper +menu: + docs_{{ .version }}: + identifier: zk-update-version + name: Update Version + parent: zk-zookeeper-guides + weight: 50 +menu_name: docs_{{ .version }} +--- \ No newline at end of file diff --git a/docs/guides/zookeeper/update-version/overview.md b/docs/guides/zookeeper/update-version/overview.md new file mode 100644 index 000000000..b3967cc03 --- /dev/null +++ b/docs/guides/zookeeper/update-version/overview.md @@ -0,0 +1,54 @@ +--- +title: Updating ZooKeeper Overview +menu: + docs_{{ .version }}: + identifier: zk-update-version-overview + name: Overview + parent: zk-update-version + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# updating ZooKeeper version Overview + +This guide will give you an overview on how KubeDB Ops-manager operator update the version of `ZooKeeper` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [ZooKeeper](/docs/guides/zookeeper/concepts/zookeeper.md) + - [ZooKeeperOpsRequest](/docs/guides/zookeeper/concepts/opsrequest.md) + +## How update version Process Works + +The following diagram shows how KubeDB Ops-manager operator used to update the version of `ZooKeeper`. Open the image in a new tab to see the enlarged version. + +
+  updating Process of ZooKeeper +
Fig: updating Process of ZooKeeper
+
+ +The updating process consists of the following steps: + +1. At first, a user creates a `ZooKeeper` Custom Resource (CR). + +2. `KubeDB` Provisioner operator watches the `ZooKeeper` CR. + +3. When the operator finds a `ZooKeeper` CR, it creates required number of `PetSets` and other kubernetes native resources like secrets, services, etc. + +4. Then, in order to update the version of the `ZooKeeper` database the user creates a `ZooKeeperOpsRequest` CR with the desired version. + +5. `KubeDB` Ops-manager operator watches the `ZooKeeperOpsRequest` CR. + +6. When it finds a `ZooKeeperOpsRequest` CR, it halts the `ZooKeeper` object which is referred from the `ZooKeeperOpsRequest`. So, the `KubeDB` Provisioner operator doesn't perform any operations on the `ZooKeeper` object during the updating process. + +7. By looking at the target version from `ZooKeeperOpsRequest` CR, `KubeDB` Ops-manager operator updates the images of all the `PetSets`. After each image update, the operator performs some checks such as if the oplog is synced and database size is almost same or not. + +8. After successfully updating the `PetSets` and their `Pods` images, the `KubeDB` Ops-manager operator updates the image of the `ZooKeeper` object to reflect the updated state of the database. + +9. After successfully updating of `ZooKeeper` object, the `KubeDB` Ops-manager operator resumes the `ZooKeeper` object so that the `KubeDB` Provisioner operator can resume its usual operations. + +In the next doc, we are going to show a step-by-step guide on updating of a ZooKeeper database using updateVersion operation. \ No newline at end of file diff --git a/docs/guides/zookeeper/update-version/update-version.md b/docs/guides/zookeeper/update-version/update-version.md new file mode 100644 index 000000000..a5a710429 --- /dev/null +++ b/docs/guides/zookeeper/update-version/update-version.md @@ -0,0 +1,275 @@ +--- +title: Updating ZooKeeper Cluster +menu: + docs_{{ .version }}: + identifier: zk-cluster-update-version + name: Update Version + parent: zk-update-version + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# update version of ZooKeeper Cluster + +This guide will show you how to use `KubeDB` Ops-manager operator to update the version of `ZooKeeper` Cluster. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install `KubeDB` Provisioner and Ops-manager operator in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [ZooKeeper](/docs/guides/zookeeper/concepts/zookeeper.md) + - [ZooKeeperOpsRequest](/docs/guides/zookeeper/concepts/opsrequest.md) + - [Updating Overview](/docs/guides/zookeeper/update-version/overview.md) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/examples/zookeeper](/docs/examples/zookeeper) directory of [kubedb/docs](https://github.com/kube/docs) repository. + +## Prepare ZooKeeper cluster + +Now, we are going to deploy a `ZooKeeper` cluster with version `3.8.3`. + +### Deploy ZooKeeper + +In this section, we are going to deploy a ZooKeeper cluster. Then, in the next section we will update the version of the database using `ZooKeeperOpsRequest` CRD. Below is the YAML of the `ZooKeeper` CR that we are going to create, + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: ZooKeeper +metadata: + name: zk-quickstart + namespace: demo +spec: + version: "3.8.3" + adminServerPort: 8080 + replicas: 4 + storage: + resources: + requests: + storage: "1Gi" + storageClassName: "standard" + accessModes: + - ReadWriteOnce + deletionPolicy: "WipeOut" + +``` + +Let's create the `ZooKeeper` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/zookeeper/update-version/zookeeper.yaml +zookeeper.kubedb.com/zk-quickstart created +``` + +Now, wait until `zk-quickstart` created has status `Ready`. i.e, + +```bash +$ kubectl get zk -n demo +NAME VERSION STATUS AGE +zk-quickstart 3.12.12 Ready 109s +``` + +We are now ready to apply the `ZooKeeperOpsRequest` CR to update this database. + +### update ZooKeeper Version + +Here, we are going to update `ZooKeeper` cluster from `3.8.3` to `3.9.1`. + +#### Create ZooKeeperOpsRequest: + +In order to update the version of the cluster, we have to create a `ZooKeeperOpsRequest` CR with your desired version that is supported by `KubeDB`. Below is the YAML of the `ZooKeeperOpsRequest` CR that we are going to create, + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: upgrade-topology + namespace: demo +spec: + databaseRef: + name: zk-quickstart + type: UpdateVersion + updateVersion: + targetVersion: 3.9.1 + timeout: 5m + apply: IfReady +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing operation on `zk-quickstart` ZooKeeper database. +- `spec.type` specifies that we are going to perform `UpdateVersion` on our database. +- `spec.updateVersion.targetVersion` specifies the expected version of the database `3.9.1`. +- Have a look [here](/docs/guides/zookeeper/concepts/opsrequest.md#spectimeout) on the respective sections to understand the `readinessCriteria`, `timeout` & `apply` fields. + +Let's create the `ZooKeeperOpsRequest` CR we have shown above, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/zookeeper/update-version/zk-version-upgrade-ops.yaml +zookeeperopsrequest.ops.kubedb.com/upgrade-topology created +``` + +#### Verify ZooKeeper version updated successfully + +If everything goes well, `KubeDB` Ops-manager operator will update the image of `ZooKeeper` object and related `PetSets` and `Pods`. + +Let's wait for `ZooKeeperOpsRequest` to be `Successful`. Run the following command to watch `ZooKeeperOpsRequest` CR, + +```bash +$ kubectl get zookeeperopsrequest -n demo +Every 2.0s: kubectl get zookeeperopsrequest -n demo +NAME TYPE STATUS AGE +upgrade-topology UpdateVersion Successful 84s +``` + +We can see from the above output that the `ZooKeeperOpsRequest` has succeeded. If we describe the `ZooKeeperOpsRequest` we will get an overview of the steps that were followed to update the database version. + +```bash +$ kubectl describe zookeeperopsrequest -n demo upgrade-topology +Name: upgrade-topology +Namespace: demo +Labels: +Annotations: +API Version: ops.kubedb.com/v1alpha1 +Kind: ZooKeeperOpsRequest +Metadata: + Creation Timestamp: 2024-10-23T10:46:27Z + Generation: 1 + Resource Version: 1112190 + UID: 6a1baef3-74cb-4a44-9b8f-f4fa49a4cfca +Spec: + Apply: IfReady + Database Ref: + Name: zk-quickstart + Timeout: 5m + Type: UpdateVersion + Update Version: + Target Version: 3.9.1 +Status: + Conditions: + Last Transition Time: 2024-10-23T10:46:27Z + Message: Zookeeper ops-request has started to update version + Observed Generation: 1 + Reason: UpdateVersion + Status: True + Type: UpdateVersion + Last Transition Time: 2024-10-23T10:46:35Z + Message: successfully reconciled the ZooKeeper with updated version + Observed Generation: 1 + Reason: UpdatePetSets + Status: True + Type: UpdatePetSets + Last Transition Time: 2024-10-23T10:49:25Z + Message: Successfully Restarted ZooKeeper nodes + Observed Generation: 1 + Reason: RestartPods + Status: True + Type: RestartPods + Last Transition Time: 2024-10-23T10:46:40Z + Message: get pod; ConditionStatus:True; PodName:zk-quickstart-0 + Observed Generation: 1 + Status: True + Type: GetPod--zk-quickstart-0 + Last Transition Time: 2024-10-23T10:46:40Z + Message: evict pod; ConditionStatus:True; PodName:zk-quickstart-0 + Observed Generation: 1 + Status: True + Type: EvictPod--zk-quickstart-0 + Last Transition Time: 2024-10-23T10:46:45Z + Message: running pod; ConditionStatus:False + Observed Generation: 1 + Status: False + Type: RunningPod + Last Transition Time: 2024-10-23T10:47:25Z + Message: get pod; ConditionStatus:True; PodName:zk-quickstart-1 + Observed Generation: 1 + Status: True + Type: GetPod--zk-quickstart-1 + Last Transition Time: 2024-10-23T10:47:25Z + Message: evict pod; ConditionStatus:True; PodName:zk-quickstart-1 + Observed Generation: 1 + Status: True + Type: EvictPod--zk-quickstart-1 + Last Transition Time: 2024-10-23T10:48:05Z + Message: get pod; ConditionStatus:True; PodName:zk-quickstart-2 + Observed Generation: 1 + Status: True + Type: GetPod--zk-quickstart-2 + Last Transition Time: 2024-10-23T10:48:05Z + Message: evict pod; ConditionStatus:True; PodName:zk-quickstart-2 + Observed Generation: 1 + Status: True + Type: EvictPod--zk-quickstart-2 + Last Transition Time: 2024-10-23T10:48:45Z + Message: get pod; ConditionStatus:True; PodName:zk-quickstart-3 + Observed Generation: 1 + Status: True + Type: GetPod--zk-quickstart-3 + Last Transition Time: 2024-10-23T10:48:45Z + Message: evict pod; ConditionStatus:True; PodName:zk-quickstart-3 + Observed Generation: 1 + Status: True + Type: EvictPod--zk-quickstart-3 + Last Transition Time: 2024-10-23T10:49:25Z + Message: Successfully updated ZooKeeper version + Observed Generation: 1 + Reason: Successful + Status: True + Type: Successful + Observed Generation: 1 + Phase: Successful +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Starting 10m KubeDB Ops-manager Operator Start processing for ZooKeeperOpsRequest: demo/upgrade-topology + Normal Starting 10m KubeDB Ops-manager Operator Pausing ZooKeeper database: demo/zk-quickstart + Normal Successful 10m KubeDB Ops-manager Operator Successfully paused ZooKeeper database: demo/zk-quickstart for ZooKeeperOpsRequest: upgrade-topology + Normal UpdatePetSets 10m KubeDB Ops-manager Operator successfully reconciled the ZooKeeper with updated version + Warning get pod; ConditionStatus:True; PodName:zk-quickstart-0 10m KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:zk-quickstart-0 + Warning evict pod; ConditionStatus:True; PodName:zk-quickstart-0 10m KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:zk-quickstart-0 + Warning running pod; ConditionStatus:False 10m KubeDB Ops-manager Operator running pod; ConditionStatus:False + Warning get pod; ConditionStatus:True; PodName:zk-quickstart-1 9m25s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:zk-quickstart-1 + Warning evict pod; ConditionStatus:True; PodName:zk-quickstart-1 9m25s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:zk-quickstart-1 + Warning get pod; ConditionStatus:True; PodName:zk-quickstart-2 8m45s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:zk-quickstart-2 + Warning evict pod; ConditionStatus:True; PodName:zk-quickstart-2 8m45s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:zk-quickstart-2 + Warning get pod; ConditionStatus:True; PodName:zk-quickstart-3 8m5s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:zk-quickstart-3 + Warning evict pod; ConditionStatus:True; PodName:zk-quickstart-3 8m5s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:zk-quickstart-3 + Normal RestartPods 7m25s KubeDB Ops-manager Operator Successfully Restarted ZooKeeper nodes + Normal Starting 7m25s KubeDB Ops-manager Operator Resuming ZooKeeper database: demo/zk-quickstart + Normal Successful 7m25s KubeDB Ops-manager Operator +``` + +Now, we are going to verify whether the `ZooKeeper` and the related `PetSets` and their `Pods` have the new version image. Let's check, + +```bash +$ kubectl get zk -n demo zk-quickstart -o=jsonpath='{.spec.version}{"\n"}' +3.9.1 + +$ kubectl get petset -n demo zk-quickstart -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/zookeeper:3.9.1@sha256:21365fd1bd55cacd6bf556394d6dcb76ad559ad3767adc304e62db205e4b10b7 + +$ kubectl get pods -n demo zk-quickstart-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/zookeeper:3.9.1 +``` + +You can see from above, our `ZooKeeper` cluster has been updated with the new version. So, the updateVersion process is successfully completed. + +## Cleaning Up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete zk -n demo zk-quickstart +kubectl delete zookeeperopsrequest -n demo upgrade-topology +``` \ No newline at end of file diff --git a/docs/images/day-2-operation/zookeeper/zk-version-update.svg b/docs/images/day-2-operation/zookeeper/zk-version-update.svg new file mode 100644 index 000000000..74049aa6f --- /dev/null +++ b/docs/images/day-2-operation/zookeeper/zk-version-update.svg @@ -0,0 +1,4 @@ + + + +
1.Create zookeeper
1.Create zookeeper
2.Watch
2.Watch
3.Create
3.Create
4.Initiate Upgrade
4.Initiate Upgr...
6.Pause
6.Pause
7.Update & Perform Checks
7.Update & Perform...
8.Update Image
8.Update Image
9.Resume
9.Resume
Upgrading stage
Upgrading stage
User
User                Community            Operator
           StatefulSet
Statef...
5.Watch
5.Watch            Enterprise            Operator
zookeeper OpsRequest
zookeeper OpsRe...
zookeeper
zookeeper
Updated/New
StatefulSet
Upda...
refers to
refers to
Upgraded zookeeper
Upgrad...Text is not SVG - cannot display \ No newline at end of file