260 lines
9.6 KiB
Markdown
260 lines
9.6 KiB
Markdown
---
|
||
title: "Example: Deploying Cassandra with Stateful Sets"
|
||
reviewers:
|
||
- ahmetb
|
||
content_template: templates/tutorial
|
||
weight: 30
|
||
---
|
||
|
||
{{% capture overview %}}
|
||
This tutorial shows you how to develop a native cloud [Cassandra](http://cassandra.apache.org/) deployment on Kubernetes. In this example, a custom Cassandra `SeedProvider` enables Cassandra to discover new Cassandra nodes as they join the cluster.
|
||
|
||
`StatefulSet`s make it easier to deploy stateful applications within a clustered environment. For more information on the features used in this tutorial, see the [`StatefulSet`](/docs/concepts/workloads/controllers/statefulset/) documentation.
|
||
|
||
**Cassandra on Docker**
|
||
|
||
The `Pod`s in this tutorial use the [`gcr.io/google-samples/cassandra:v13`](https://github.com/kubernetes/examples/blob/master/cassandra/image/Dockerfile)
|
||
image from Google's [container registry](https://cloud.google.com/container-registry/docs/).
|
||
The Docker image above is based on [debian-base](https://github.com/kubernetes/kubernetes/tree/master/build/debian-base)
|
||
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`.
|
||
|
||
| ENV VAR | DEFAULT VALUE |
|
||
| ------------- |:-------------: |
|
||
| `CASSANDRA_CLUSTER_NAME` | `'Test Cluster'` |
|
||
| `CASSANDRA_NUM_TOKENS` | `32` |
|
||
| `CASSANDRA_RPC_ADDRESS` | `0.0.0.0` |
|
||
|
||
{{% /capture %}}
|
||
|
||
{{% capture objectives %}}
|
||
* Create and validate a Cassandra headless [`Service`](/docs/concepts/services-networking/service/).
|
||
* Use a [`StatefulSet`](/docs/concepts/workloads/controllers/statefulset/) to create a Cassandra ring.
|
||
* Validate the [`StatefulSet`](/docs/concepts/workloads/controllers/statefulset/).
|
||
* Modify the [`StatefulSet`](/docs/concepts/workloads/controllers/statefulset/).
|
||
* Delete the [`StatefulSet`](/docs/concepts/workloads/controllers/statefulset/) and its [`Pod`s](/docs/concepts/workloads/pods/pod/).
|
||
{{% /capture %}}
|
||
|
||
{{% capture prerequisites %}}
|
||
To complete this tutorial, you should already have a basic familiarity with [`Pod`s](/docs/concepts/workloads/pods/pod/), [`Service`s](/docs/concepts/services-networking/service/), and [`StatefulSet`s](/docs/concepts/workloads/controllers/statefulset/). In addition, you should:
|
||
|
||
* [Install and Configure](/docs/tasks/tools/install-kubectl/) the `kubectl` command-line tool
|
||
|
||
* Download [`cassandra-service.yaml`](/examples/application/cassandra/cassandra-service.yaml)
|
||
and [`cassandra-statefulset.yaml`](/examples/application/cassandra/cassandra-statefulset.yaml)
|
||
|
||
* Have a supported Kubernetes cluster running
|
||
|
||
{{< note >}}
|
||
**Note:** Please read the [getting started guides](/docs/setup/pick-right-solution/) if you do not already have a cluster.
|
||
{{< /note >}}
|
||
|
||
### Additional Minikube Setup Instructions
|
||
|
||
{{< caution >}}
|
||
**Caution:** [Minikube](/docs/getting-started-guides/minikube/) defaults to 1024MB of memory and 1 CPU. Running Minikube with the default resource configuration may result in insufficient resource errors during this tutorial. To avoid these errors, we recommend running Minikube with 5 GB of memory and 4 CPUs:
|
||
|
||
```shell
|
||
minikube start --memory 5120 --cpus=4
|
||
```
|
||
{{< /caution >}}
|
||
|
||
{{% /capture %}}
|
||
|
||
{{% capture lessoncontent %}}
|
||
## Creating a Cassandra Headless Service
|
||
|
||
A Kubernetes [`Service`](/docs/concepts/services-networking/service/) describes a set of [`Pod`s](/docs/concepts/workloads/pods/pod/) that perform the same task.
|
||
|
||
The following `Service` is used for DNS lookups between Cassandra `Pod`s and clients within the Kubernetes cluster.
|
||
|
||
{{< codenew file="application/cassandra/cassandra-service.yaml" >}}
|
||
|
||
1. Launch a terminal window in the directory you downloaded the manifest files.
|
||
1. Create a `Service` to track all Cassandra `StatefulSet` nodes from the `cassandra-service.yaml` file:
|
||
|
||
```shell
|
||
kubectl create -f https://k8s.io/examples/application/cassandra/cassandra-service.yaml
|
||
```
|
||
|
||
### Validating (optional)
|
||
|
||
Get the Cassandra `Service`.
|
||
|
||
```shell
|
||
kubectl get svc cassandra
|
||
```
|
||
|
||
The response is
|
||
|
||
```
|
||
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||
cassandra None <none> 9042/TCP 45s
|
||
```
|
||
|
||
Service creation failed if anything else is returned. Read [Debug Services](/docs/tasks/debug-application-cluster/debug-service/) for common issues.
|
||
|
||
## Using a StatefulSet to Create a Cassandra Ring
|
||
|
||
The `StatefulSet` manifest, included below, creates a Cassandra ring that consists of three `Pod`s.
|
||
|
||
{{< note >}}
|
||
**Note:** This example uses the default provisioner for Minikube. Please update the following `StatefulSet` for the cloud you are working with.
|
||
{{< /note >}}
|
||
|
||
{{< codenew file="application/cassandra/cassandra-statefulset.yaml" >}}
|
||
|
||
1. Update the `StatefulSet` if necessary.
|
||
1. Create the Cassandra `StatefulSet` from the `cassandra-statefulset.yaml` file:
|
||
|
||
```shell
|
||
kubectl create -f https://k8s.io/examples/application/cassandra/cassandra-statefulset.yaml
|
||
```
|
||
|
||
## Validating The Cassandra StatefulSet
|
||
|
||
1. Get the Cassandra `StatefulSet`:
|
||
|
||
```shell
|
||
kubectl get statefulset cassandra
|
||
```
|
||
|
||
The response should be:
|
||
|
||
```
|
||
NAME DESIRED CURRENT AGE
|
||
cassandra 3 0 13s
|
||
```
|
||
|
||
The `StatefulSet` resource deploys `Pod`s sequentially.
|
||
|
||
1. Get the `Pod`s to see the ordered creation status:
|
||
|
||
```shell
|
||
kubectl get pods -l="app=cassandra"
|
||
```
|
||
|
||
The response should be:
|
||
|
||
```shell
|
||
NAME READY STATUS RESTARTS AGE
|
||
cassandra-0 1/1 Running 0 1m
|
||
cassandra-1 0/1 ContainerCreating 0 8s
|
||
```
|
||
|
||
Please note that it may take several minutes for all three `Pod`s to deploy. Once they are deployed, the same command returns:
|
||
|
||
```
|
||
NAME READY STATUS RESTARTS AGE
|
||
cassandra-0 1/1 Running 0 10m
|
||
cassandra-1 1/1 Running 0 9m
|
||
cassandra-2 1/1 Running 0 8m
|
||
```
|
||
|
||
3. Run the Cassandra [nodetool](https://wiki.apache.org/cassandra/NodeTool) to display the status of the ring.
|
||
|
||
```shell
|
||
kubectl exec -it cassandra-0 -- nodetool status
|
||
```
|
||
|
||
The response should look something like this:
|
||
|
||
```
|
||
Datacenter: DC1-K8Demo
|
||
======================
|
||
Status=Up/Down
|
||
|/ State=Normal/Leaving/Joining/Moving
|
||
-- Address Load Tokens Owns (effective) Host ID Rack
|
||
UN 172.17.0.5 83.57 KiB 32 74.0% e2dd09e6-d9d3-477e-96c5-45094c08db0f Rack1-K8Demo
|
||
UN 172.17.0.4 101.04 KiB 32 58.8% f89d6835-3a42-4419-92b3-0e62cae1479c Rack1-K8Demo
|
||
UN 172.17.0.6 84.74 KiB 32 67.1% a6a1e8c2-3dc5-4417-b1a0-26507af2aaad Rack1-K8Demo
|
||
```
|
||
|
||
## Modifying the Cassandra StatefulSet
|
||
|
||
Use `kubectl edit` to modify the size of a Cassandra `StatefulSet`.
|
||
|
||
1. Run the following command:
|
||
|
||
```shell
|
||
kubectl edit statefulset cassandra
|
||
```
|
||
|
||
This command opens an editor in your terminal. The line you need to change is the `replicas` field. The following sample is an excerpt of the `StatefulSet` file:
|
||
|
||
```yaml
|
||
# Please edit the object below. Lines beginning with a '#' will be ignored,
|
||
# and an empty file will abort the edit. If an error occurs while saving this file will be
|
||
# reopened with the relevant failures.
|
||
#
|
||
apiVersion: apps/v1 # for versions before 1.9.0 use apps/v1beta2
|
||
kind: StatefulSet
|
||
metadata:
|
||
creationTimestamp: 2016-08-13T18:40:58Z
|
||
generation: 1
|
||
labels:
|
||
app: cassandra
|
||
name: cassandra
|
||
namespace: default
|
||
resourceVersion: "323"
|
||
selfLink: /apis/apps/v1/namespaces/default/statefulsets/cassandra
|
||
uid: 7a219483-6185-11e6-a910-42010a8a0fc0
|
||
spec:
|
||
replicas: 3
|
||
```
|
||
|
||
2. Change the number of replicas to 4, and then save the manifest.
|
||
|
||
The `StatefulSet` now contains 4 `Pod`s.
|
||
|
||
1. Get the Cassandra `StatefulSet` to verify:
|
||
|
||
```shell
|
||
kubectl get statefulset cassandra
|
||
```
|
||
|
||
The response should be
|
||
|
||
```
|
||
NAME DESIRED CURRENT AGE
|
||
cassandra 4 4 36m
|
||
```
|
||
|
||
{{% /capture %}}
|
||
|
||
{{% capture cleanup %}}
|
||
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.
|
||
|
||
{{< warning >}}
|
||
**Warning:** Depending on the storage class and reclaim policy, deleting the `PersistentVolumeClaim`s may cause the associated volumes to also be deleted. Never assume you’ll be able to access data if its volume claims are deleted.
|
||
{{< /warning >}}
|
||
|
||
1. Run the following commands (chained together into a single command) to delete everything in the Cassandra `StatefulSet`:
|
||
|
||
```shell
|
||
grace=$(kubectl get po cassandra-0 -o=jsonpath='{.spec.terminationGracePeriodSeconds}') \
|
||
&& kubectl delete statefulset -l app=cassandra \
|
||
&& echo "Sleeping $grace" \
|
||
&& sleep $grace \
|
||
&& kubectl delete pvc -l app=cassandra
|
||
```
|
||
|
||
1. Run the following command to delete the Cassandra `Service`.
|
||
|
||
```shell
|
||
kubectl delete service -l app=cassandra
|
||
```
|
||
|
||
{{% /capture %}}
|
||
|
||
{{% capture whatsnext %}}
|
||
|
||
* Learn how to [Scale a `StatefulSet`](/docs/tasks/run-application/scale-stateful-set/).
|
||
* Learn more about the [`KubernetesSeedProvider`](https://github.com/kubernetes/examples/blob/master/cassandra/java/src/main/java/io/k8s/cassandra/KubernetesSeedProvider.java)
|
||
* See more custom [Seed Provider Configurations](https://git.k8s.io/examples/cassandra/java/README.md)
|
||
|
||
{{% /capture %}}
|
||
|