helm/infrastructure/subcharts/kong/charts/cassandra/README.md

   1 # Cassandra
   2 A Cassandra Chart for Kubernetes
   3
   4 ## Install Chart
   5 To install the Cassandra Chart into your Kubernetes cluster (This Chart requires persistent volume by default, you may need to create a storage class before install chart. To create storage class, see [Persist data](#persist_data) section)
   6
   7 ```bash
   8 helm install --namespace "cassandra" -n "cassandra" incubator/cassandra
   9 ```
  10
  11 After installation succeeds, you can get a status of Chart
  12
  13 ```bash
  14 helm status "cassandra"
  15 ```
  16
  17 If you want to delete your Chart, use this command
  18 ```bash
  19 helm delete  --purge "cassandra"
  20 ```
  21
  22 ## Persist data
  23 You need to create `StorageClass` before able to persist data in persistent volume.
  24 To create a `StorageClass` on Google Cloud, run the following
  25
  26 ```bash
  27 kubectl create -f sample/create-storage-gce.yaml
  28 ```
  29
  30 And set the following values in `values.yaml`
  31
  32 ```yaml
  33 persistence:
  34   enabled: true
  35 ```
  36
  37 If you want to create a `StorageClass` on other platform, please see documentation here [https://kubernetes.io/docs/user-guide/persistent-volumes/](https://kubernetes.io/docs/user-guide/persistent-volumes/)
  38
  39 When running a cluster without persistence, the termination of a pod will first initiate a decommissioning of that pod.
  40 Depending on the amount of data stored inside the cluster this may take a while. In order to complete a graceful
  41 termination, pods need to get more time for it. Set the following values in `values.yaml`:
  42
  43 ```yaml
  44 podSettings:
  45   terminationGracePeriodSeconds: 1800
  46 ```
  47
  48 ## Install Chart with specific cluster size
  49 By default, this Chart will create a cassandra with 3 nodes. If you want to change the cluster size during installation, you can use `--set config.cluster_size={value}` argument. Or edit `values.yaml`
  50
  51 For example:
  52 Set cluster size to 5
  53
  54 ```bash
  55 helm install --namespace "cassandra" -n "cassandra" --set config.cluster_size=5 incubator/cassandra/
  56 ```
  57
  58 ## Install Chart with specific resource size
  59 By default, this Chart will create a cassandra with CPU 2 vCPU and 4Gi of memory which is suitable for development environment.
  60 If you want to use this Chart for production, I would recommend to update the CPU to 4 vCPU and 16Gi. Also increase size of `max_heap_size` and `heap_new_size`.
  61 To update the settings, edit `values.yaml`
  62
  63 ## Install Chart with specific node
  64 Sometime you may need to deploy your cassandra to specific nodes to allocate resources. You can use node selector by edit `nodes.enabled=true` in `values.yaml`
  65 For example, you have 6 vms in node pools and you want to deploy cassandra to node which labeled as `cloud.google.com/gke-nodepool: pool-db`
  66
  67 Set the following values in `values.yaml`
  68
  69 ```yaml
  70 nodes:
  71   enabled: true
  72   selector:
  73     nodeSelector:
  74       cloud.google.com/gke-nodepool: pool-db
  75 ```
  76
  77 ## Configuration
  78
  79 The following table lists the configurable parameters of the Cassandra chart and their default values.
  80
  81 | Parameter                  | Description                                     | Default                                                    |
  82 | -----------------------    | ---------------------------------------------   | ---------------------------------------------------------- |
  83 | `image.repo`                         | `cassandra` image repository                    | `cassandra`                                                |
  84 | `image.tag`                          | `cassandra` image tag                           | `3.11.3`                                                   |
  85 | `image.pullPolicy`                   | Image pull policy                               | `Always` if `imageTag` is `latest`, else `IfNotPresent`    |
  86 | `image.pullSecrets`                  | Image pull secrets                              | `nil`                                                      |
  87 | `config.cluster_domain`              | The name of the cluster domain.                 | `cluster.local`                                            |
  88 | `config.cluster_name`                | The name of the cluster.                        | `cassandra`                                                |
  89 | `config.cluster_size`                | The number of nodes in the cluster.             | `3`                                                        |
  90 | `config.seed_size`                   | The number of seed nodes used to bootstrap new clients joining the cluster.                            | `2` |
  91 | `config.seeds`                       | The comma-separated list of seed nodes.         | Automatically generated according to `.Release.Name` and `config.seed_size` |
  92 | `config.num_tokens`                  | Initdb Arguments                                | `256`                                                      |
  93 | `config.dc_name`                     | Initdb Arguments                                | `DC1`                                                      |
  94 | `config.rack_name`                   | Initdb Arguments                                | `RAC1`                                                     |
  95 | `config.endpoint_snitch`             | Initdb Arguments                                | `SimpleSnitch`                                             |
  96 | `config.max_heap_size`               | Initdb Arguments                                | `2048M`                                                    |
  97 | `config.heap_new_size`               | Initdb Arguments                                | `512M`                                                     |
  98 | `config.ports.cql`                   | Initdb Arguments                                | `9042`                                                     |
  99 | `config.ports.thrift`                | Initdb Arguments                                | `9160`                                                     |
 100 | `config.ports.agent`                 | The port of the JVM Agent (if any)              | `nil`                                                      |
 101 | `config.start_rpc`                   | Initdb Arguments                                | `false`                                                    |
 102 | `configOverrides`                    | Overrides config files in /etc/cassandra dir    | `{}`                                                       |
 103 | `commandOverrides`                   | Overrides default docker command                | `[]`                                                       |
 104 | `argsOverrides`                      | Overrides default docker args                   | `[]`                                                       |
 105 | `env`                                | Custom env variables                            | `{}`                                                       |
 106 | `persistence.enabled`                | Use a PVC to persist data                       | `true`                                                     |
 107 | `persistence.storageClass`           | Storage class of backing PVC                    | `nil` (uses alpha storage class annotation)                |
 108 | `persistence.accessMode`             | Use volume as ReadOnly or ReadWrite             | `ReadWriteOnce`                                            |
 109 | `persistence.size`                   | Size of data volume                             | `10Gi`                                                     |
 110 | `resources`                          | CPU/Memory resource requests/limits             | Memory: `4Gi`, CPU: `2`                                    |
 111 | `service.type`                       | k8s service type exposing ports, e.g. `NodePort`| `ClusterIP`                                                |
 112 | `podManagementPolicy`                | podManagementPolicy of the StatefulSet          | `OrderedReady`                                             |
 113 | `podDisruptionBudget`                | Pod distruption budget                          | `{}`                                                       |
 114 | `podAnnotations`                     | pod annotations for the StatefulSet             | `{}`                                                       |
 115 | `updateStrategy.type`                | UpdateStrategy of the StatefulSet               | `OnDelete`                                                 |
 116 | `livenessProbe.initialDelaySeconds`  | Delay before liveness probe is initiated        | `90`                                                       |
 117 | `livenessProbe.periodSeconds`        | How often to perform the probe                  | `30`                                                       |
 118 | `livenessProbe.timeoutSeconds`       | When the probe times out                        | `5`                                                        |
 119 | `livenessProbe.successThreshold`     | Minimum consecutive successes for the probe to be considered successful after having failed.           | `1` |
 120 | `livenessProbe.failureThreshold`     | Minimum consecutive failures for the probe to be considered failed after having succeeded.             | `3` |
 121 | `readinessProbe.initialDelaySeconds` | Delay before readiness probe is initiated       | `90`                                                       |
 122 | `readinessProbe.periodSeconds`       | How often to perform the probe                  | `30`                                                       |
 123 | `readinessProbe.timeoutSeconds`      | When the probe times out                        | `5`                                                        |
 124 | `readinessProbe.successThreshold`    | Minimum consecutive successes for the probe to be considered successful after having failed.           | `1` |
 125 | `readinessProbe.failureThreshold`    | Minimum consecutive failures for the probe to be considered failed after having succeeded.             | `3` |
 126 | `rbac.create`                        | Specifies whether RBAC resources should be created                                                  | `true` |
 127 | `serviceAccount.create`              | Specifies whether a ServiceAccount should be created                                                | `true` |
 128 | `serviceAccount.name`                | The name of the ServiceAccount to use           |                                                            |
 129 | `backup.enabled`                     | Enable backup on chart installation             | `false`                                                    |
 130 | `backup.schedule`                    | Keyspaces to backup, each with cron time        |                                                            |
 131 | `backup.annotations`                 | Backup pod annotations                          | iam.amazonaws.com/role: `cain`                             |
 132 | `backup.image.repo`                  | Backup image repository                         | `nuvo/cain`                                                |
 133 | `backup.image.tag`                   | Backup image tag                                | `0.4.1`                                                    |
 134 | `backup.extraArgs`                   | Additional arguments for cain                   | `[]`                                                       |
 135 | `backup.env`                         | Backup environment variables                    | AWS_REGION: `us-east-1`                                    |
 136 | `backup.resources`                   | Backup CPU/Memory resource requests/limits      | Memory: `1Gi`, CPU: `1`                                    |
 137 | `backup.destination`                 | Destination to store backup artifacts           | `s3://bucket/cassandra`                                    |
 138 | `exporter.enabled`                   | Enable Cassandra exporter                       | `false`                                                    |
 139 | `exporter.image.repo`                | Exporter image repository                       | `criteord/cassandra_exporter`                              |
 140 | `exporter.image.tag`                 | Exporter image tag                              | `2.0.2`                                                    |
 141 | `exporter.port`                      | Exporter port                                   | `5556`                                                     |
 142 | `exporter.jvmOpts`                   | Exporter additional JVM options                 |                                                            |
 143 | `affinity`                           | Kubernetes node affinity                        | `{}`                                                       |
 144 | `tolerations`                        | Kubernetes node tolerations                     | `[]`                                                       |
 145
 146
 147 ## Scale cassandra
 148 When you want to change the cluster size of your cassandra, you can use the helm upgrade command.
 149
 150 ```bash
 151 helm upgrade --set config.cluster_size=5 cassandra incubator/cassandra
 152 ```
 153
 154 ## Get cassandra status
 155 You can get your cassandra cluster status by running the command
 156
 157 ```bash
 158 kubectl exec -it --namespace cassandra $(kubectl get pods --namespace cassandra -l app=cassandra-cassandra -o jsonpath='{.items[0].metadata.name}') nodetool status
 159 ```
 160
 161 Output
 162 ```bash
 163 Datacenter: asia-east1
 164 ======================
 165 Status=Up/Down
 166 |/ State=Normal/Leaving/Joining/Moving
 167 --  Address    Load       Tokens       Owns (effective)  Host ID                               Rack
 168 UN  10.8.1.11  108.45 KiB  256          66.1%             410cc9da-8993-4dc2-9026-1dd381874c54  a
 169 UN  10.8.4.12  84.08 KiB  256          68.7%             96e159e1-ef94-406e-a0be-e58fbd32a830  c
 170 UN  10.8.3.6   103.07 KiB  256          65.2%             1a42b953-8728-4139-b070-b855b8fff326  b
 171 ```
 172
 173 ## Benchmark
 174 You can use [cassandra-stress](https://docs.datastax.com/en/cassandra/3.0/cassandra/tools/toolsCStress.html) tool to run the benchmark on the cluster by the following command
 175
 176 ```bash
 177 kubectl exec -it --namespace cassandra $(kubectl get pods --namespace cassandra -l app=cassandra-cassandra -o jsonpath='{.items[0].metadata.name}') cassandra-stress
 178 ```
 179
 180 Example of `cassandra-stress` argument
 181  - Run both read and write with ration 9:1
 182  - Operator total 1 million keys with uniform distribution
 183  - Use QUORUM for read/write
 184  - Generate 50 threads
 185  - Generate result in graph
 186  - Use NetworkTopologyStrategy with replica factor 2
 187
 188 ```bash
 189 cassandra-stress mixed ratio\(write=1,read=9\) n=1000000 cl=QUORUM -pop dist=UNIFORM\(1..1000000\) -mode native cql3 -rate threads=50 -log file=~/mixed_autorate_r9w1_1M.log -graph file=test2.html title=test revision=test2 -schema "replication(strategy=NetworkTopologyStrategy, factor=2)"
 190 ```