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/README.md b/docs/guides/zookeeper/README.md index b5c5c9d8b..8b2ad1a94 100644 --- a/docs/guides/zookeeper/README.md +++ b/docs/guides/zookeeper/README.md @@ -25,6 +25,11 @@ aliases: | Grafana Dashboards | ✓ | | Externally manageable Auth Secret | ✓ | | Reconfigurable Health Checker | ✓ | +| TLS: Add, Remove, Update, Rotate ( [Cert Manager](https://cert-manager.io/docs/) ) | ✓ | +| Automated Version update | ✓ | +| Automatic Vertical Scaling | ✓ | +| Automated Horizontal Scaling | ✓ | +| Automated Volume Expansion | ✓ | | Backup/Recovery: Instant, Scheduled ([KubeStash](https://kubestash.com/)) | ✓ | | Persistent Volume | ✓ | | Initializing from Snapshot ( [Stash](https://stash.run/) ) | ✓ | diff --git a/docs/guides/zookeeper/concepts/opsrequest.md b/docs/guides/zookeeper/concepts/opsrequest.md new file mode 100644 index 000000000..51d2ec5f7 --- /dev/null +++ b/docs/guides/zookeeper/concepts/opsrequest.md @@ -0,0 +1,388 @@ +--- +title: ZooKeeperOpsRequest CRD +menu: + docs_{{ .version }}: + identifier: zk-opsrequest + name: ZooKeeperOpsRequest + parent: zk-concepts-zookeeper + weight: 25 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# ZooKeeperOpsRequest + +## What is ZooKeeperOpsRequest + +`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. + +## ZooKeeperOpsRequest CRD Specifications + +Like any official Kubernetes resource, a `ZooKeeperOpsRequest` has `TypeMeta`, `ObjectMeta`, `Spec` and `Status` sections. + +Here, some sample `ZooKeeperOpsRequest` CRs for different administrative operations is given below: + +**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. + +```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 +``` + +**Sample `ZooKeeperOpsRequest` Objects for Horizontal Scaling of the database Cluster:** + +You can scale up and down your zookeeper cluster horizontally. +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: horizontal-scale-up + namespace: demo +spec: + type: HorizontalScaling + databaseRef: + name: zk-quickstart + horizontalScaling: + replicas: 5 +``` + +**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: ZooKeeperOpsRequest +metadata: + name: zookeeper-vscale + namespace: demo +spec: + type: VerticalScaling + databaseRef: + name: zookeeper + verticalScaling: + node: + resources: + requests: + cpu: 600m + memory: 1.2Gi + limits: + cpu: 1 + memory: 2Gi +``` + +**Sample `ZooKeeperOpsRequest` Objects for Reconfiguring database cluster:** + +Reconfigure your cluster by applying new configuration via `zoo.conf` file. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: myops-reconfigure-config + namespace: demo +spec: + apply: IfReady + databaseRef: + name: zk-quickstart + type: Reconfigure + configuration: + applyConfig: + zoo.cfg: | + max_connections = 300 + read_buffer_size = 1048576 +``` + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: myops-reconfigure-config + namespace: demo +spec: + apply: IfReady + databaseRef: + name: zk-quickstart + type: Reconfigure + configuration: + removeCustomConfig: true +``` + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: myops-reconfigure-config + namespace: demo +spec: + apply: IfReady + databaseRef: + name: zk-quickstart + type: Reconfigure + configuration: + configSecret: + name: new-config-secret +``` + +**Sample `ZooKeeperOpsRequest` Objects for Volume Expansion of database cluster:** + +You can expand ZooKeeper storage volume in both online and offline mode. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: online-volume-expansion + namespace: demo +spec: + type: VolumeExpansion + databaseRef: + name: zk-quickstart + volumeExpansion: + mode: "Online" + node: 3Gi +``` + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: offline-volume-expansion + namespace: demo +spec: + type: VolumeExpansion + databaseRef: + name: zk-quickstart + volumeExpansion: + mode: "Offline" + node: 4Gi +``` + +**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. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: myops-rotate + namespace: demo +spec: + type: ReconfigureTLS + databaseRef: + name: zk-quickstart + tls: + rotateCertificates: true +``` + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: zkops-update-issuer + namespace: demo +spec: + type: ReconfigureTLS + databaseRef: + name: zk-quickstart + tls: + issuerRef: + name: zk-new-issuer + kind: Issuer + apiGroup: "cert-manager.io" +``` + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ZooKeeperOpsRequest +metadata: + name: myops-remove + namespace: demo +spec: + type: ReconfigureTLS + databaseRef: + name: zk-quickstart + tls: + remove: true +``` + +Here, we are going to describe the various sections of a `ZooKeeperOpsRequest` crd. + +A `ZooKeeperOpsRequest` object has the following fields in the `spec` section. + +### spec.databaseRef + +`spec.databaseRef` is a required field that point to the [ZooKeeper](/docs/guides/zookeeper/concepts/zookeeper.md) object for which the administrative operations will be performed. This field consists of the following sub-field: + +- **spec.databaseRef.name :** specifies the name of the [ZooKeeper](/docs/guides/zookeeper/concepts/zookeeper.md) object. + +### 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 `ZooKeeperOpsRequest`. + +- `Upgrade` / `UpdateVersion` +- `HorizontalScaling` +- `VerticalScaling` +- `VolumeExpansion` +- `Reconfigure` +- `ReconfigureTLS` +- `Restart` + +> 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`. + +### spec.updateVersion + +If you want to update your ZooKeeper version, you have to specify the `spec.updateVersion` section that specifies the desired version information. This field consists of the following sub-field: + +- `spec.updateVersion.targetVersion` refers to a [ZooKeeperVersion](/docs/guides/zookeeper/concepts/catalog.md) CR that contains the ZooKeeper version information where you want to update. + + +### spec.horizontalScaling + +If you want to scale-up or scale-down your ZooKeeper cluster or different components of it, you have to specify `spec.horizontalScaling` section. This field consists of the following sub-field: + +- `spec.horizontalScaling.replicas` indicates the desired number of pods for ZooKeeper cluster after scaling. For example, if your cluster currently has 4 pods, and you want to add additional 2 pods then you have to specify 6 in `spec.horizontalScaling.replicas` field. Similarly, if you want to remove one pod from the cluster, you have to specify 3 in `spec.horizontalScaling.replicas` field. + +### spec.verticalScaling + +`spec.verticalScaling` is a required field specifying the information of `ZooKeeper` resources like `cpu`, `memory` etc. that will be scaled. This field consists of the following sub-fields: + +- `spec.verticalScaling.node` indicates the desired resources for PetSet of ZooKeeper after scaling. + +It has the below structure: + +```yaml +requests: + memory: "600Mi" + cpu: "0.5" +limits: + memory: "800Mi" + cpu: "0.8" +``` + +Here, when you specify the resource request, the scheduler uses this information to decide which node to place the container of the Pod on and when you specify a resource limit for the container, the `kubelet` enforces those limits so that the running container is not allowed to use more of that resource than the limit you set. You can found more details from [here](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). + +### spec.volumeExpansion + +> To use the volume expansion feature the storage class must support volume expansion + +If you want to expand the volume of your ZooKeeper standalone or cluster, you have to specify `spec.volumeExpansion` section. This field consists of the following sub-field: + +- `spec.volumeExpansion.node` indicates the desired size for the persistent volume of a ZooKeeper. +- `spec.volumeExpansion.mode` indicates the mode of volume expansion. It can be `online` or `offline` based on the storage class. + + +All of them refer to Quantity types of Kubernetes. + +Example usage of this field is given below: + +```yaml +spec: + volumeExpansion: + node: "2Gi" +``` + +This will expand the volume size of all the ZooKeeper nodes to 2 GB. + +### spec.configuration + +If you want to reconfigure your Running ZooKeeper cluster or different components of it with new custom configuration, you have to specify `spec.configuration` section. This field consists of the following sub-field: + +- `configSecret` points to a secret in the same namespace of a ZooKeeper resource, which contains the new custom configurations. If there are any configSecret set before in the database, this secret will replace it. +- `applyConfig` contains the new custom config as a string which will be merged with the previous configuration. + +- `applyConfig` is a map where key supports 1 values, namely `zoo.conf`. + +```yaml + applyConfig: + zoo.cfg: | + max_connections = 300 + read_buffer_size = 1048576 +``` + +- `removeCustomConfig` is a boolean field. Specify this field to true if you want to remove all the custom configuration from the deployed ZooKeeper server. + +### spec.tls + +If you want to reconfigure the TLS configuration of your ZooKeeper cluster i.e. add TLS, remove TLS, update issuer/cluster issuer or Certificates and rotate the certificates, you have to specify `spec.tls` section. This field consists of the following sub-field: + +- `spec.tls.issuerRef` specifies the issuer name, kind and api group. +- `spec.tls.certificates` specifies the certificates. You can learn more about this field from [here](/docs/guides/zookeeper/concepts/zookeeper.md#spectls). +- `spec.tls.rotateCertificates` specifies that we want to rotate the certificate of this database. +- `spec.tls.remove` specifies that we want to remove tls from this database. +- `spec.tls.sslMode` specifies what will be the ssl mode of the cluster allowed values are: disable,allow,prefer,require,verify-ca,verify-full +- `spec.tls.clientAuthMode` specifies what will be the client authentication mode of the cluster allowed values are: md5,scram,cert + +### spec.timeout +As we internally retry the ops request steps multiple times, This `timeout` field helps the users to specify the timeout for those steps of the ops request (in second). +If a step doesn't finish within the specified timeout, the ops request will result in failure. + +### spec.apply +This field controls the execution of obsRequest depending on the database state. It has two supported values: `Always` & `IfReady`. +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. + + +### ZooKeeperOpsRequest `Status` + +`.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 `ZooKeeperOpsRequest`. It can have the following three values: + +| Phase | Meaning | +|-------------|-------------------------------------------------------------------------------------| +| 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 `ZooKeeperOpsRequest` controller. + +### status.conditions + +`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. ZooKeeperOpsRequest has the following types of conditions: + +| Type | | Meaning | +|--------------------------------|---|---------------------------------------------------------------------------| +| `Progressing` | | Specifies that the operation is now in the progressing state | +| `Successful` | | Specifies such a state that the operation on the database was successful. | +| `DatabasePauseSucceeded` | | Specifies such a state that the database is paused by the operator | +| `ResumeDatabase` | | Specifies such a state that the database is resumed by the operator | +| `Failed` | | Specifies such a state that the operation on the database failed. | +| `UpdatePetSetResources` | | Specifies such a state that the PetSet resources has been updated | +| `UpdatePetSet` | | Specifies such a state that the PetSet has been updated | +| `IssueCertificatesSucceeded` | | Specifies such a state that the tls certificate issuing is successful | +| `UpdateDatabase` | | Specifies such a state that the CR of ZooKeeper is updated | + +- The `status` field is a string, with possible values `True`, `False`, and `Unknown`. + - `status` will be `True` if the current transition succeeded. + - `status` will be `False` if the current transition failed. + - `status` will be `Unknown` if the current transition was denied. +- The `message` field is a human-readable message indicating details about the condition. +- The `reason` field is a unique, one-word, CamelCase reason for the condition's last transition. +- The `lastTransitionTime` field provides a timestamp for when the operation last transitioned from one state to another. +- The `observedGeneration` shows the most recent condition transition generation observed by the controller. diff --git a/docs/guides/zookeeper/concepts/zookeeper.md b/docs/guides/zookeeper/concepts/zookeeper.md index c712b3067..ce50f57f3 100644 --- a/docs/guides/zookeeper/concepts/zookeeper.md +++ b/docs/guides/zookeeper/concepts/zookeeper.md @@ -33,9 +33,13 @@ spec: replicas: 3 disableAuth: false adminServerPort: 8080 + clientSecurePort: 2182 authSecret: name: zk-auth externallyManaged: false + keystoreCredSecret: + name: zk-quickstart-keystore-cred + enableSSL: true storage: storageClassName: "standard" accessModes: @@ -83,6 +87,16 @@ spec: timeoutSeconds: 10 failureThreshold: 2 disableWriteCheck: false + tls: + certificates: + - alias: server + secretName: zk-quickstart-server-cert + - alias: client + secretName: zk-quickstart-client-cert + issuerRef: + apiGroup: cert-manager.io + kind: Issuer + name: zookeeper-ca-issuer ``` @@ -94,6 +108,11 @@ spec: - `3.8.3` - `3.9.1` +### spec.replicas + +`spec.replicas` the number of nodes in ZooKeeper cluster. + +KubeDB uses `PodDisruptionBudget` to ensure that majority of these replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that quorum is maintained. ### spec.disableAuth @@ -166,6 +185,77 @@ ZooKeeper managed by KubeDB can be monitored with builtin-Prometheus and Prometh `spec.configSecret` is an optional field that allows users to provide custom configuration for ZooKeeper. This field accepts a [`VolumeSource`](https://github.com/kubernetes/api/blob/release-1.11/core/v1/types.go#L47). So you can use any Kubernetes supported volume source such as `configMap`, `secret`, `azureDisk` etc. +### spec.enableSSL + +`spec.enableSSL` is an `optional` field that specifies whether to enable TLS to HTTP layer. The default value of this field is `false`. + +```yaml +spec: + enableSSL: true +``` + +### spec.tls + +`spec.tls` specifies the TLS/SSL configurations. The KubeDB operator supports TLS management by using the [cert-manager](https://cert-manager.io/). Currently, the operator only supports the `PKCS#8` encoded certificates. + +```yaml +spec: + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: zk-issuer + certificates: + - alias: server + privateKey: + encoding: PKCS8 + secretName: zk-client-cert + subject: + organizations: + - kubedb + - alias: http + privateKey: + encoding: PKCS8 + secretName: zk-server-cert + subject: + organizations: + - kubedb +``` + +The `spec.tls` contains the following fields: + +- `tls.issuerRef` - is an `optional` field that references to the `Issuer` or `ClusterIssuer` custom resource object of [cert-manager](https://cert-manager.io/docs/concepts/issuer/). It is used to generate the necessary certificate secrets for ZooKeeper. If the `issuerRef` is not specified, the operator creates a self-signed CA and also creates necessary certificate (valid: 365 days) secrets using that CA. + - `apiGroup` - is the group name of the resource that is being referenced. Currently, the only supported value is `cert-manager.io`. + - `kind` - is the type of resource that is being referenced. The supported values are `Issuer` and `ClusterIssuer`. + - `name` - is the name of the resource ( `Issuer` or `ClusterIssuer` ) that is being referenced. + +- `tls.certificates` - is an `optional` field that specifies a list of certificate configurations used to configure the certificates. It has the following fields: + - `alias` - represents the identifier of the certificate. It has the following possible value: + - `server` - is used for the server certificate configuration. + - `client` - is used for the client certificate configuration. + + - `secretName` - ( `string` | `"-alias-cert"` ) - specifies the k8s secret name that holds the certificates. + + - `subject` - specifies an `X.509` distinguished name (DN). It has the following configurable fields: + - `organizations` ( `[]string` | `nil` ) - is a list of organization names. + - `organizationalUnits` ( `[]string` | `nil` ) - is a list of organization unit names. + - `countries` ( `[]string` | `nil` ) - is a list of country names (ie. Country Codes). + - `localities` ( `[]string` | `nil` ) - is a list of locality names. + - `provinces` ( `[]string` | `nil` ) - is a list of province names. + - `streetAddresses` ( `[]string` | `nil` ) - is a list of street addresses. + - `postalCodes` ( `[]string` | `nil` ) - is a list of postal codes. + - `serialNumber` ( `string` | `""` ) is a serial number. + + For more details, visit [here](https://golang.org/pkg/crypto/x509/pkix/#Name). + + - `duration` ( `string` | `""` ) - is the period during which the certificate is valid. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `"300m"`, `"1.5h"` or `"20h45m"`. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". + - `renewBefore` ( `string` | `""` ) - is a specifiable time before expiration duration. + - `dnsNames` ( `[]string` | `nil` ) - is a list of subject alt names. + - `ipAddresses` ( `[]string` | `nil` ) - is a list of IP addresses. + - `uris` ( `[]string` | `nil` ) - is a list of URI Subject Alternative Names. + - `emailAddresses` ( `[]string` | `nil` ) - is a list of email Subject Alternative Names. + + ### spec.podTemplate KubeDB allows providing a template for database pod through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the PetSet created for ZooKeeper server. 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..387b83777 --- /dev/null +++ b/docs/guides/zookeeper/restart/restart.md @@ -0,0 +1,206 @@ +--- +title: Restart ZooKeeper +menu: + docs_{{ .version }}: + identifier: zk-restart-details + name: Restart Ensemble + 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 +zk-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). +- 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..e843f2d8b --- /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). + +# Overview of ZooKeeper Version Update + +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`. + +8. After successfully updating the `PetSets` and their `Pods` images, the `KubeDB` Ops-manager operator updates the version field 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](/docs/guides/zookeeper/update-version/update-version.md) 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..5b1cf5450 --- /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 Ensemble + +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 Ensemble + +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: 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/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.9.1 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..97259b804 --- /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 Update
4.Initiate Upgr...
6.Pause
6.Pause
7.Update & Perform Checks
7.Update & Perform...
8.Update Image
8.Update Image
9.Resume
9.Resume
Updating stage
Updating 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
Updated zookeeper
Upgrad...Text is not SVG - cannot display \ No newline at end of file