|
1 | | -<!-- EXCLUDE_FROM_DOCS BEGIN --> |
| 1 | +# Example: Cassandra with StatefulSets on Kubernetes |
2 | 2 |
|
3 | | -> :warning: :warning: Follow this tutorial on the Kubernetes website: |
4 | | -> https://kubernetes.io/docs/tutorials/stateful-application/cassandra/. |
5 | | -> Otherwise some of the URLs will not work properly. |
6 | 3 |
|
7 | | -# Cloud Native Deployments of Cassandra using Kubernetes |
8 | | -<!-- EXCLUDE_FROM_DOCS END --> |
| 4 | +This directory contains the source code and Kubernetes manifests for Cassandra |
| 5 | +deployment with StatefulSets tutorial. |
9 | 6 |
|
10 | | -{% capture overview %} |
11 | | -This tutorial shows you how to develop a native cloud [Cassandra](http://cassandra.apache.org/) deployment on Kubernetes. In this instance, a custom Cassandra `SeedProvider` enables Cassandra to discover new Cassandra nodes as they join the cluster. |
12 | | - |
13 | | -Deploying stateful distributed applications, like Cassandra, within a clustered environment can be challenging. StatefulSets greatly simplify this process. Please read about [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) for more information about the features used in this tutorial. |
14 | | - |
15 | | -**Cassandra Docker** |
16 | | - |
17 | | -The Pods use the [`gcr.io/google-samples/cassandra:v12`](https://github.com/kubernetes/examples/blob/master/cassandra/image/Dockerfile) |
18 | | -image from Google's [container registry](https://cloud.google.com/container-registry/docs/). |
19 | | -The docker is based on `debian:jessie` and includes OpenJDK 8. This image includes a standard Cassandra installation from the Apache Debian repo. By using environment variables you can change values that are inserted into `cassandra.yaml`. |
20 | | - |
21 | | -| ENV VAR | DEFAULT VALUE | |
22 | | -| ------------- |:-------------: | |
23 | | -| CASSANDRA_CLUSTER_NAME | 'Test Cluster' | |
24 | | -| CASSANDRA_NUM_TOKENS | 32 | |
25 | | -| CASSANDRA_RPC_ADDRESS | 0.0.0.0 | |
26 | | - |
27 | | -{% endcapture %} |
28 | | - |
29 | | -{% capture objectives %} |
30 | | -* Create and Validate a Cassandra headless `Service`. |
31 | | -* Use a `StatefulSet` to create a Cassandra ring. |
32 | | -* Validate the `StatefulSet`. |
33 | | -* Modify the `StatefulSet`. |
34 | | -* Delete the `StatefulSet` and its `Pods`. |
35 | | -{% endcapture %} |
36 | | - |
37 | | -{% capture prerequisites %} |
38 | | -To complete this tutorial, you should already have a basic familiarity with [Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/), [Services](https://kubernetes.io/docs/concepts/services-networking/service/), and [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/). In addition, you should: |
39 | | - |
40 | | -* [Install and Configure](https://kubernetes.io/docs/tasks/tools/install-kubectl/) the `kubectl` command line |
41 | | - |
42 | | -* Download [cassandra-service.yaml](https://kubernetes.io/docs/tutorials/stateful-application/cassandra-service.yaml) and [cassandra-statefulset.yaml](https://kubernetes.io/docs/tutorials/stateful-application/cassandra-statefulset.yaml) |
43 | | - |
44 | | -* Have a supported Kubernetes Cluster running |
45 | | - |
46 | | -**Note:** Please read the [getting started guides](https://kubernetes.io/docs/setup/pick-right-solution/) if you do not already have a cluster. |
47 | | -{: .note} |
48 | | - |
49 | | -### Additional Minikube Setup Instructions |
50 | | - |
51 | | -**Caution:** [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) defaults to 1024MB of memory and 1 CPU which results in an insufficient resource errors during this tutorial. |
52 | | -{: .caution} |
53 | | - |
54 | | -To avoid these errors, run minikube with: |
55 | | - |
56 | | - minikube start --memory 5120 --cpus=4 |
57 | | - |
58 | | -{% endcapture %} |
59 | | - |
60 | | -{% capture lessoncontent %} |
61 | | -## Creating a Cassandra Headless Service |
62 | | -A Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/) describes a set of [Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/) that perform the same task. |
63 | | - |
64 | | -The following `Service` is used for DNS lookups between Cassandra Pods and clients within the Kubernetes Cluster. |
65 | | - |
66 | | -1. Launch a terminal window in the directory you downloaded the manifest files. |
67 | | -2. Create a `Service` to track all Cassandra StatefulSet Nodes from the `cassandra-service.yaml` file: |
68 | | - |
69 | | - kubectl create -f cassandra-service.yaml |
70 | | - |
71 | | -{% include code.html language="yaml" file="cassandra-service.yaml" ghlink="/docs/tutorials/stateful-application/cassandra-service.yaml" %} |
72 | | - |
73 | | -### Validating (optional) |
74 | | - |
75 | | -Get the Cassandra `Service`. |
76 | | - |
77 | | - kubectl get svc cassandra |
78 | | - |
79 | | -The response should be |
80 | | - |
81 | | - NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE |
82 | | - cassandra None <none> 9042/TCP 45s |
83 | | - |
84 | | -If anything else returns, the service was not successfully created. Read [Debug Services](https://kubernetes.io/docs/tasks/debug-application-cluster/debug-service/) for common issues. |
85 | | - |
86 | | -## Using a StatefulSet to Create a Cassandra Ring |
87 | | - |
88 | | -The StatefulSet manifest, included below, creates a Cassandra ring that consists of three Pods. |
89 | | - |
90 | | -**Note:** This example uses the default provisioner for Minikube. Please update the following StatefulSet for the cloud you are working with. |
91 | | -{: .note} |
92 | | - |
93 | | -1. Update the StatefulSet if necessary. |
94 | | -2. Create the Cassandra StatefulSet from the `cassandra-statefulset.yaml` file: |
95 | | - |
96 | | - kubectl create -f cassandra-statefulset.yaml |
97 | | - |
98 | | -{% include code.html language="yaml" file="cassandra-statefulset.yaml" ghlink="/docs/tutorials/stateful-application/cassandra-statefulset.yaml" %} |
99 | | - |
100 | | -## Validating The Cassandra StatefulSet |
101 | | - |
102 | | -1. Get the Cassandra StatefulSet: |
103 | | - |
104 | | - kubectl get statefulset cassandra |
105 | | - |
106 | | - The response should be |
107 | | - |
108 | | - NAME DESIRED CURRENT AGE |
109 | | - cassandra 3 0 13s |
110 | | - |
111 | | - The StatefulSet resource deploys Pods sequentially. |
112 | | - |
113 | | -2. Get the Pods to see the ordered creation status: |
114 | | - |
115 | | - kubectl get pods -l="app=cassandra" |
116 | | - |
117 | | - The response should be |
118 | | - |
119 | | - NAME READY STATUS RESTARTS AGE |
120 | | - cassandra-0 1/1 Running 0 1m |
121 | | - cassandra-1 0/1 ContainerCreating 0 8s |
122 | | - |
123 | | - **Note:** It can take up to ten minutes for all three Pods to deploy. |
124 | | - {: .note} |
125 | | - |
126 | | - Once all Pods are deployed, the same command returns: |
127 | | - |
128 | | - NAME READY STATUS RESTARTS AGE |
129 | | - cassandra-0 1/1 Running 0 10m |
130 | | - cassandra-1 1/1 Running 0 9m |
131 | | - cassandra-2 1/1 Running 0 8m |
132 | | - |
133 | | -3. Run the Cassandra utility nodetool to display the status of the ring. |
134 | | - |
135 | | - kubectl exec cassandra-0 -- nodetool status |
136 | | - |
137 | | - The response is: |
138 | | - |
139 | | - Datacenter: DC1-K8Demo |
140 | | - ====================== |
141 | | - Status=Up/Down |
142 | | - |/ State=Normal/Leaving/Joining/Moving |
143 | | - -- Address Load Tokens Owns (effective) Host ID Rack |
144 | | - UN 172.17.0.5 83.57 KiB 32 74.0% e2dd09e6-d9d3-477e-96c5-45094c08db0f Rack1-K8Demo |
145 | | - UN 172.17.0.4 101.04 KiB 32 58.8% f89d6835-3a42-4419-92b3-0e62cae1479c Rack1-K8Demo |
146 | | - UN 172.17.0.6 84.74 KiB 32 67.1% a6a1e8c2-3dc5-4417-b1a0-26507af2aaad Rack1-K8Demo |
147 | | - |
148 | | -## Modifying the Cassandra StatefulSet |
149 | | -Use `kubectl edit` to modify the size of a Cassandra StatefulSet. |
150 | | - |
151 | | -1. Run the following command: |
152 | | - |
153 | | - kubectl edit statefulset cassandra |
154 | | - |
155 | | - This command opens an editor in your terminal. The line you need to change is the `replicas` field. |
156 | | - |
157 | | - **Note:** The following sample is an excerpt of the StatefulSet file. |
158 | | - {: .note} |
159 | | - |
160 | | - ```yaml |
161 | | - # Please edit the object below. Lines beginning with a '#' will be ignored, |
162 | | - # and an empty file will abort the edit. If an error occurs while saving this file will be |
163 | | - # reopened with the relevant failures. |
164 | | - # |
165 | | - apiVersion: apps/v1beta1 |
166 | | - kind: StatefulSet |
167 | | - metadata: |
168 | | - creationTimestamp: 2016-08-13T18:40:58Z |
169 | | - generation: 1 |
170 | | - labels: |
171 | | - app: cassandra |
172 | | - name: cassandra |
173 | | - namespace: default |
174 | | - resourceVersion: "323" |
175 | | - selfLink: /apis/apps/v1beta1/namespaces/default/statefulsets/cassandra |
176 | | - uid: 7a219483-6185-11e6-a910-42010a8a0fc0 |
177 | | - spec: |
178 | | - replicas: 3 |
179 | | - ``` |
180 | | -
|
181 | | -2. Change the number of replicas to 4, and then save the manifest. |
182 | | -
|
183 | | - The StatefulSet now contains 4 Pods. |
184 | | -
|
185 | | -3. Get the Cassandra StatefulSet to verify: |
186 | | -
|
187 | | - kubectl get statefulset cassandra |
188 | | -
|
189 | | - The response should be |
190 | | -
|
191 | | - NAME DESIRED CURRENT AGE |
192 | | - cassandra 4 4 36m |
193 | | - |
194 | | -{% endcapture %} |
195 | | -
|
196 | | -{% capture cleanup %} |
197 | | -Deleting or scaling a StatefulSet down does not delete the volumes associated with the StatefulSet. This ensures safety first: your data is more valuable than an auto purge of all related StatefulSet resources. |
198 | | -
|
199 | | -**Warning:** Depending on the storage class and reclaim policy, deleting the Persistent Volume Claims may cause the associated volumes to also be deleted. Never assume you’ll be able to access data if its volume claims are deleted. |
200 | | -{: .warning} |
201 | | -
|
202 | | -1. Run the following commands to delete everything in a `StatefulSet`: |
203 | | - |
204 | | - grace=$(kubectl get po cassandra-0 -o=jsonpath='{.spec.terminationGracePeriodSeconds}') \ |
205 | | - && kubectl delete statefulset -l app=cassandra \ |
206 | | - && echo "Sleeping $grace" \ |
207 | | - && sleep $grace \ |
208 | | - && kubectl delete pvc -l app=cassandra |
209 | | - |
210 | | -2. Run the following command to delete the Cassandra `Service`. |
211 | | - |
212 | | - kubectl delete service -l app=cassandra |
213 | | - |
214 | | -{% endcapture %} |
215 | | - |
216 | | -{% capture whatsnext %} |
217 | | -* Learn how to [Scale a StatefulSet](https://kubernetes.io/docs/tasks/run-application/scale-stateful-set/). |
218 | | -* Learn more about the [KubernetesSeedProvider](https://github.com/kubernetes/examples/blob/master/cassandra/java/src/main/java/io/k8s/cassandra/KubernetesSeedProvider.java) |
219 | | -* See more custom [Seed Provider Configurations](https://git.k8s.io/examples/cassandra/java/README.md) |
220 | | - |
221 | | -{% endcapture %} |
222 | | - |
223 | | -{% include templates/tutorial.md %} |
224 | | - |
225 | | -<!-- BEGIN MUNGE: GENERATED_ANALYTICS --> |
226 | | -[]() |
227 | | -<!-- END MUNGE: GENERATED_ANALYTICS --> |
| 7 | +Follow this tutorial at https://kubernetes.io/docs/tutorials/stateful-application/cassandra/. |
0 commit comments