Updating documentation (#77)

* Updating documentation Signed-off-by: SrishT <[email protected]> * Updating documentation and adding version validation Signed-off-by: SrishT <[email protected]> * Webhook changes Signed-off-by: SrishT <[email protected]> * Addressing review comments Signed-off-by: SrishT <[email protected]> * Addressing review comments Signed-off-by: SrishT <[email protected]> * Changing default storage class Signed-off-by: SrishT <[email protected]> Co-authored-by: SrishT <[email protected]>
pravega · Oct 1, 2020 · bdc1a35 · bdc1a35
1 parent 829966c
commit bdc1a35
Show file tree

Hide file tree

Showing 16 changed files with 188 additions and 177 deletions.
diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@ The project is currently alpha. While no breaking API changes are currently plan
 
 ## Overview
 
-[Bookkeeper](https://bookkeeper.apache.org/) A scalable, fault-tolerant, and low-latency storage service optimized for real-time workloads.
+[Bookkeeper](https://bookkeeper.apache.org/) is a scalable, fault-tolerant, and low-latency storage service optimized for real-time workloads.
 
 The Bookkeeper Operator manages Bookkeeper clusters deployed to Kubernetes and automates tasks related to operating a Bookkeeper cluster.
 
@@ -42,40 +42,26 @@ The Bookkeeper Operator manages Bookkeeper clusters deployed to Kubernetes and a
 
 ## Quickstart
 
+We recommend using our [helm charts](charts) for all installation and upgrades (but not for rollbacks at the moment since helm rollbacks are still experimental). The helm charts for bookkeeper operator (version 0.1.2 onwards) and bookkeeper cluster (version 0.5.0 onwards) are published in [https://charts.pravega.io](https://charts.pravega.io/). To add this repository to your Helm repos, use the following command:
+```
+helm repo add pravega https://charts.pravega.io
+```
+There are manual deployment, upgrade and rollback options available as well.
+
 ### Install the Operator
 
 > Note: If you are running on Google Kubernetes Engine (GKE), please [check this first](doc/development.md#installation-on-google-kubernetes-engine).
 
-We recommend using helm to deploy a Bookkeeper Operator. Check out the [helm installation](charts/bookkeeper-operator/README.md) document for instructions.
+To understand how to deploy a Bookkeeper Operator using helm, refer to [this](charts/bookkeeper-operator#installing-the-chart).
+
 #### Install the Operator in Test Mode
  The Operator can be run in `test mode` if we want to deploy the Bookkeeper Cluster on minikube or on a cluster with very limited resources by setting `testmode: true` in `values.yaml` file. Operator running in test mode skips the minimum replica requirement checks. Test mode provides a bare minimum setup and is not recommended to be used in production environments.
 
 ### Install a sample Bookkeeper cluster
-> Note that the Bookkeeper cluster must be installed in the same namespace as the Zookeeper cluster.
-
-If the Bookkeeper cluster is expected to work with Pravega, we need to create a ConfigMap which needs to have the following values
-
-| KEY | VALUE |
-|---|---|
-| *PRAVEGA_CLUSTER_NAME* | Name of Pravega Cluster using this BookKeeper Cluster |
-| *WAIT_FOR* | Zookeeper URL |
-
-The name of this ConfigMap needs to be mentioned in the field `envVars` present in the BookKeeper Spec. For more details about this ConfigMap refer to [this](doc/bookkeeper-options.md#bookkeeper-custom-configuration).
-
-Helm can be used to install a sample Bookkeeper cluster with the release name `bookkeeper`.
-
-```
-$ helm install bookkeeper charts/bookkeeper --set zookeeperUri=[ZOOKEEPER_HOST] --set pravegaClusterName=[CLUSTER_NAME]
-```
-
-where:
-
-- **[ZOOKEEPER_HOST]** is the Zookeeper service endpoint of your Zookeeper deployment (e.g. `zookeeper-client:2181`). It expects the zookeeper service URL in the given format `<service-name>:<port-number>`
-- **[CLUSTER_NAME]** is the name of the Pravega cluster (i.e. this field is optional and needs to be provided only if we expect this bookkeeper cluster to work with [Pravega](https://github.com/pravega/pravega)).
 
-Check out the [Bookkeeper Helm Chart](charts/bookkeeper) for more a complete list of installation parameters.
+To understand how to deploy a bookkeeper cluster using helm, refer to [this](charts/bookkeeper#installing-the-chart).
 
-Verify that the cluster instances and its components are being created.
+Once the bookkeeper cluster with release name `bookkeeper` has been created, use the following command to verify that the cluster instances and its components are being created.
 
 ```
 $ kubectl get bk
@@ -131,9 +117,8 @@ For upgrading the bookkeeper operator check the document [operator-upgrade](doc/
 ### Uninstall the Bookkeeper cluster
 
 ```
-$ helm uninstall bookkeeper
+$ helm uninstall [BOOKKEEPER_RELEASE_NAME]
 ```
-Here `bookkeeper` is the bookkeeper cluster release name.
 
 Once the Bookkeeper cluster has been deleted, make sure to check that the zookeeper metadata has been cleaned up before proceeding with the deletion of the operator. This can be confirmed with the presence of the following log message in the operator logs.
 ```
@@ -142,7 +127,7 @@ zookeeper metadata deleted
 
 However, if the operator fails to delete this metadata from zookeeper, you will instead find the following log message in the operator logs.
 ```
-failed to cleanup <bookkeeper-cluster-name> metadata from zookeeper (znode path: /pravega/<pravega-cluster-name>): <error-msg>
+failed to cleanup [CLUSTER_NAME] metadata from zookeeper (znode path: /pravega/[PRAVEGA_CLUSTER_NAME]): <error-msg>
 ```
 
 The operator additionally sends out a `ZKMETA_CLEANUP_ERROR` event to notify the user about this failure. The user can check this event by doing `kubectl get events`. The following is the sample describe output of the event that is generated by the operator in such a case
@@ -183,9 +168,8 @@ Events:  <none>
 > Note that the Bookkeeper clusters managed by the Bookkeeper operator will NOT be deleted even if the operator is uninstalled.
 
 ```
-$ helm uninstall bookkeeper-operator
+$ helm uninstall [BOOKKEEPER_OPERATOR_RELEASE_NAME]
 ```
-Here `bookkeeper-operator` is the operator release name.
 
 ### Manual installation
 

diff --git a/charts/bookkeeper-operator/README.md b/charts/bookkeeper-operator/README.md
@@ -11,37 +11,41 @@ This chart bootstraps a [Bookkeeper Operator](https://github.com/pravega/bookkee
   - Helm 3.2.1+
   - An existing Apache Zookeeper 3.6.1 cluster. This can be easily deployed using our [Zookeeper Operator](https://github.com/pravega/zookeeper-operator)
   - Cert-Manager v0.15.0+ or some other certificate management solution in order to manage the webhook service certificates. This can be easily deployed by referring to [this](https://cert-manager.io/docs/installation/kubernetes/)
-- An Issuer and a Certificate (either self-signed or CA signed) in the same namespace that the Bookkeeper Operator will be installed (refer to [this](https://github.com/pravega/bookkeeper-operator/blob/master/deploy/certificate.yaml) manifest to create a self-signed certificate in the default namespace)
-> The name of the certificate (*webhookCert.certName*), the name of the secret created by this certificate (*webhookCert.secretName*), the tls.crt (*webhookCert.crt*) and tls.key (*webhookCert.key*) need to be specified against the corresponding fields in the values.yaml file, or can be provided with the install command as shown [here](#installing-the-chart).
-The values *tls.crt* and *tls.key* are contained in the secret which is created by the certificate and can be obtained using the following command
-```
-kubectl get secret <secret-name> -o yaml | grep tls.
-```
-
+  - An Issuer and a Certificate (either self-signed or CA signed) in the same namespace that the Bookkeeper Operator will be installed (refer to [this](https://github.com/pravega/bookkeeper-operator/blob/master/deploy/certificate.yaml) manifest to create a self-signed certificate in the default namespace)
 
 ## Installing the Chart
 
-To install the chart with the release name `my-release`:
+To install the bookkeeper-operator chart, use the following commands:
 
 ```
-$ helm install my-release bookkeeper-operator --set webhookCert.generate=false --set webhookCert.certName=<cert-name> --set webhookCert.secretName=<secret-name>
+$ helm repo add pravega https://charts.pravega.io
+$ helm repo update
+$ helm install [RELEASE_NAME] pravega/bookkeeper-operator --version=[VERSION] --set webhookCert.certName=[CERT_NAME] --set webhookCert.secretName=[SECRET_NAME]
 ```
+where:
+- **[RELEASE_NAME]** is the release name for the bookkeeper-operator chart
+- **[DEPLOYMENT_NAME]** is the name of the bookkeeper-operator deployment so created. (If [RELEASE_NAME] contains the string `bookkeeper-operator`, `[DEPLOYMENT_NAME] = [RELEASE_NAME]`, else `[DEPLOYMENT_NAME] = [RELEASE_NAME]-bookkeeper-operator`. The [DEPLOYMENT_NAME] can however be overridden by providing `--set fullnameOverride=[DEPLOYMENT_NAME]` along with the helm install command)
+- **[VERSION]** can be any stable release version for bookkeeper-operator from 0.1.3 onwards
+- **[CERT_NAME]** is the name of the certificate created as a prerequisite
+- **[SECRET_NAME]** is the name of the secret created by the above certificate
+
+This command deploys a bookkeeper-operator on the Kubernetes cluster in its default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation.
 
-The command deploys bookkeeper operator on the Kubernetes cluster in the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation.
+>Note: If the bookkeeper-operator version is 0.1.2, webhookCert.certName and webhookCert.secretName should not be set. Also in this case, cert-manager and the certificate/issuer do not need to be deployed as prerequisites.
 
 ## Uninstalling the Chart
 
-To uninstall/delete the `my-release` deployment:
+To uninstall/delete the bookkeeper-operator chart, use the following command:
 
 ```
-$ helm uninstall my-release
+$ helm uninstall [RELEASE_NAME]
 ```
 
-The command removes all the Kubernetes components associated with the chart and deletes the release.
+This command removes all the Kubernetes components associated with the chart and deletes the release.
 
 ## Configuration
 
-The following table lists the configurable parameters of the Bookkeeper operator chart and their default values.
+The following table lists the configurable parameters of the bookkeeper-operator chart and their default values.
 
 | Parameter | Description | Default |
 | ----- | ----------- | ------ |

diff --git a/charts/bookkeeper-operator/templates/webhook.yaml b/charts/bookkeeper-operator/templates/webhook.yaml
@@ -23,14 +23,15 @@ metadata:
   labels:
 {{ include "bookkeeper-operator.commonLabels" . | indent 4 }}
   annotations:
-    cert-manager.io/inject-ca-from: {{ .Release.Namespace }}/{{ .Values.certName }}
+    cert-manager.io/inject-ca-from: {{ .Release.Namespace }}/{{ .Values.webhookCert.certName }}
 webhooks:
 - clientConfig:
     service:
       name: bookkeeper-webhook-svc
       namespace: {{ .Release.Namespace }}
-      path: /validate-bookkeeper-pravega-io-v1beta1-bookkeepercluster
+      path: /validate-bookkeeper-pravega-io-v1alpha1-bookkeepercluster
   name: bookkeeperwebhook.pravega.io
+  failurePolicy: Fail
   rules:
   - apiGroups:
     - bookkeeper.pravega.io

diff --git a/charts/bookkeeper/README.md b/charts/bookkeeper/README.md
@@ -15,24 +15,34 @@ This chart creates a Bookkeeper cluster in [Kubernetes](http://kubernetes.io) us
 
 ## Installing the Chart
 
-To install the chart with the release name `my-release`:
+To install the bookkeeper chart, use the following commands:
 
 ```
-$ helm install my-release bookkeeper
+$ helm repo add pravega https://charts.pravega.io
+$ helm repo update
+$ helm install [RELEASE_NAME] pravega/bookkeeper --version=[VERSION] --set zookeeperUri=[ZOOKEEPER_HOST] --set pravegaClusterName=[PRAVEGA_CLUSTER_NAME] -n [NAMESPACE]
 ```
+where:
+- **[RELEASE_NAME]** is the release name for the bookkeeper chart
+- **[CLUSTER_NAME]** is the name of the bookkeeper cluster so created (if [RELEASE_NAME] contains the string `bookkeeper`, `[CLUSTER_NAME] = [RELEASE_NAME]`, else `[CLUSTER_NAME] = [RELEASE_NAME]-bookkeeper`. The [CLUSTER_NAME] can however be overridden by providing `--set fullnameOverride=[CLUSTER_NAME]` along with the helm install command)
+- **[PRAVEGA_CLUSTER_NAME]** is the name of the pravega cluster (this field is optional and needs to be provided only if we expect the bookkeeper cluster to work with [Pravega](https://github.com/pravega/pravega) and if we wish to override its default value which is `pravega`)
+- **[VERSION]** can be any stable release version for bookkeeper from 0.5.0 onwards
+- **[ZOOKEEPER_HOST]** is the zookeeper service endpoint of your zookeeper cluster deployment (default value of this field is `zookeeper-client:2181`)
+- **[NAMESPACE]** is the namespace in which you wish to deploy the bookkeeper cluster (default value for this field is `default`) The bookkeeper cluster must be installed in the same namespace as the zookeeper cluster.
 
-The command deploys bookkeeper on the Kubernetes cluster in the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation.
+This command deploys bookkeeper on the Kubernetes cluster in its default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation.
 
 ## Uninstalling the Chart
 
-To uninstall/delete the `my-release` deployment:
+To uninstall/delete the bookkeeper chart, use the following command:
 
 ```
-$ helm uninstall my-release
+$ helm uninstall [RELEASE_NAME]
 ```
 
-The command removes all the Kubernetes components associated with the chart and deletes the release.
-> Note: If you are setting blockOwnerDeletion to false during installtion, PVC's won't be removed automatically while uninstalling bookkeepercluster. PVCs have to be deleted manually.
+This command removes all the Kubernetes components associated with the chart and deletes the release.
+> Note: If blockOwnerDeletion had been set to false during bookkeeper installation, the PVCs won't be removed automatically while uninstalling the bookkeeper chart, and would need to be deleted manually.
+
 ## Configuration
 
 The following table lists the configurable parameters of the Bookkeeper chart and their default values.
@@ -47,16 +57,25 @@ The following table lists the configurable parameters of the Bookkeeper chart an
 | `pravegaClusterName` | Name of the pravega cluster | `pravega` |
 | `autoRecovery`| Enable bookkeeper auto-recovery | `true` |
 | `blockOwnerDeletion`| Enable blockOwnerDeletion | `true` |
-| `probes` | Timeout configuration of the readiness and liveness probes for the bookkeeper pods | `{}` |
+| `probes.readiness.initialDelaySeconds` | Number of seconds after the container has started before readiness probe is initiated | `20` |
+| `probes.readiness.periodSeconds` | Number of seconds in which readiness probe will be performed | `10` |
+| `probes.readiness.failureThreshold` | Number of seconds after which the readiness probe times out | `9` |
+| `probes.readiness.successThreshold` | Minimum number of consecutive successes for the readiness probe to be considered successful after having failed | `1` |
+| `probes.readiness.timeoutSeconds` | Number of times Kubernetes will retry after a readiness probe failure before restarting the container | `5` |
+| `probes.liveness.initialDelaySeconds` | Number of seconds after the container has started before liveness probe is initiated | `60` |
+| `probes.liveness.periodSeconds` | Number of seconds in which liveness probe will be performed  | `15` |
+| `probes.liveness.failureThreshold` | Number of seconds after which the liveness probe times out | `4` |
+| `probes.liveness.successThreshold` | Minimum number of consecutive successes for the liveness probe to be considered successful after having failed | `1` |
+| `probes.liveness.timeoutSeconds` | Number of times Kubernetes will retry after a liveness probe failure before restarting the container | `5` |
 | `resources.requests.cpu` | Requests for CPU resources | `1000m` |
 | `resources.requests.memory` | Requests for memory resources | `4Gi` |
 | `resources.limits.cpu` | Limits for CPU resources | `2000m` |
 | `resources.limits.memory` | Limits for memory resources | `4Gi` |
-| `storage.ledger.className` | Storage class name for bookkeeper ledgers | `standard` |
+| `storage.ledger.className` | Storage class name for bookkeeper ledgers | `` |
 | `storage.ledger.volumeSize` | Requested size for bookkeeper ledger persistent volumes | `10Gi` |
-| `storage.journal.className` | Storage class name for bookkeeper journals | `standard` |
+| `storage.journal.className` | Storage class name for bookkeeper journals | `` |
 | `storage.journal.volumeSize` | Requested size for bookkeeper journal persistent volumes | `10Gi` |
-| `storage.index.className` | Storage class name for bookkeeper index | `standard` |
+| `storage.index.className` | Storage class name for bookkeeper index | `` |
 | `storage.index.volumeSize` | Requested size for bookkeeper index persistent volumes | `10Gi` |
 | `jvmOptions.memoryOpts` | Memory Options passed to the JVM for bookkeeper performance tuning | `["-Xms1g", "-XX:MaxDirectMemorySize=2g"]` |
 | `jvmOptions.gcOpts` | Garbage Collector (GC) Options passed to the JVM for bookkeeper bookkeeper performance tuning | `[]` |

diff --git a/charts/bookkeeper/templates/bookkeeper.yaml b/charts/bookkeeper/templates/bookkeeper.yaml
@@ -19,46 +19,47 @@ spec:
   probes:
     {{- if .Values.probes.readiness }}
     readinessProbe:
-      initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
-      periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
-      failureThreshold: {{ .Values.probes.readiness.failureThreshold }}
-      successThreshold: {{ .Values.probes.readiness.successThreshold }}
-      timeoutSeconds: {{ .Values.probes.readiness.timeoutSeconds }}
+      initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds | default 20 }}
+      periodSeconds: {{ .Values.probes.readiness.periodSeconds | default 10 }}
+      failureThreshold: {{ .Values.probes.readiness.failureThreshold | default 9 }}
+      successThreshold: {{ .Values.probes.readiness.successThreshold | default 1 }}
+      timeoutSeconds: {{ .Values.probes.readiness.timeoutSeconds | default 5 }}
     {{- end }}
     {{- if .Values.probes.liveness }}
     livenessProbe:
-      initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}
-      periodSeconds: {{ .Values.probes.liveness.periodSeconds }}
-      failureThreshold: {{ .Values.probes.liveness.failureThreshold }}
-      successThreshold: {{ .Values.probes.liveness.successThreshold }}
-      timeoutSeconds: {{ .Values.probes.liveness.timeoutSeconds }}
+      initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds | default 60 }}
+      periodSeconds: {{ .Values.probes.liveness.periodSeconds | default 15 }}
+      failureThreshold: {{ .Values.probes.liveness.failureThreshold | default 4 }}
+      successThreshold: {{ .Values.probes.liveness.successThreshold | default 1 }}
+      timeoutSeconds: {{ .Values.probes.liveness.timeoutSeconds | default 5 }}
     {{- end }}
   {{- end }}
   {{- if .Values.resources }}
   resources:
-    requests:
-      cpu: {{ .Values.resources.requests.cpu | quote }}
-      memory: {{ .Values.resources.requests.memory | quote }}
-    limits:
-      cpu: {{ .Values.resources.limits.cpu | quote }}
-      memory: {{ .Values.resources.limits.memory | quote }}
+{{ toYaml .Values.resources | indent 6 }}
   {{- end }}
   storage:
     ledgerVolumeClaimTemplate:
       accessModes: [ "ReadWriteOnce" ]
+      {{- if .Values.storage.ledger.className }}
       storageClassName: {{ .Values.storage.ledger.className }}
+      {{- end }}
       resources:
         requests:
           storage: {{ .Values.storage.ledger.volumeSize }}
     journalVolumeClaimTemplate:
       accessModes: [ "ReadWriteOnce" ]
+      {{- if .Values.storage.journal.className }}
       storageClassName: {{ .Values.storage.journal.className }}
+      {{- end }}
       resources:
         requests:
           storage: {{ .Values.storage.journal.volumeSize }}
     indexVolumeClaimTemplate:
       accessModes: [ "ReadWriteOnce" ]
+      {{- if .Values.storage.index.className }}
       storageClassName: {{ .Values.storage.index.className }}
+      {{- end }}
       resources:
         requests:
           storage: {{ .Values.storage.index.volumeSize }}