kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #17995 from sftim/20191208_update_cassandra_statefulset_tutorial 

Update Cassandra StatefulSet tutorial
pull/20135/head
Kubernetes Prow Robot 2020-04-06 05:49:46 -07:00 committed by GitHub
parent f4dc270237 ded8bdb238
commit 26d14b6b56
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 93 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
content/en/docs/tutorials/stateful-application/cassandra.md
View File

@ -1,5 +1,5 @@
---
title: "Example: Deploying Cassandra with Stateful Sets"
title: "Example: Deploying Cassandra with a StatefulSet"
reviewers:
- ahmetb
content_template: templates/tutorial
@ -7,79 +7,66 @@ 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.
This tutorial shows you how to run [Apache Cassandra](http://cassandra.apache.org/) on Kubernetes. Cassandra, a database, needs persistent storage to provide data durability (application _state_). In this example, a custom Cassandra seed provider lets the database discover new Cassandra instances as they join the Cassandra cluster.
*StatefulSets* 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.
*StatefulSets* make it easier to deploy stateful applications into your Kubernetes cluster. For more information on the features used in this tutorial, see [StatefulSet](/docs/concepts/workloads/controllers/statefulset/).
**Cassandra on Docker**
The *Pods* 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` |
{{< note >}}
Cassandra and Kubernetes both use the term _node_ to mean a member of a cluster. In this
tutorial, the Pods that belong to the StatefulSet are Cassandra nodes and are members
of the Cassandra cluster (called a _ring_). When those Pods run in your Kubernetes cluster,
the Kubernetes control plane schedules those Pods onto Kubernetes
{{< glossary_tooltip text="Nodes" term_id="node" >}}.
When a Cassandra node starts, it uses a _seed list_ to bootstrap discovery of other
nodes in the ring.
This tutorial deploys a custom Cassandra seed provider that lets the database discover
new Cassandra Pods as they appear inside your Kubernetes cluster.
{{< /note >}}
{{% /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 [Pods](/docs/concepts/workloads/pods/pod/).
* Create and validate a Cassandra headless {{< glossary_tooltip text="Service" term_id="service" >}}.
* Use a {{< glossary_tooltip term_id="StatefulSet" >}} to create a Cassandra ring.
* Validate the StatefulSet.
* Modify the StatefulSet.
* Delete the StatefulSet and its {{< glossary_tooltip text="Pods" term_id="pod" >}}.
{{% /capture %}}
{{% capture prerequisites %}}
To complete this tutorial, you should already have a basic familiarity with [Pods](/docs/concepts/workloads/pods/pod/), [Services](/docs/concepts/services-networking/service/), and [StatefulSets](/docs/concepts/workloads/controllers/statefulset/). In addition, you should:
{{< include "task-tutorial-prereqs.md" >}}
* [Install and Configure](/docs/tasks/tools/install-kubectl/) the *kubectl* command-line tool
To complete this tutorial, you should already have a basic familiarity with {{< glossary_tooltip text="Pods" term_id="pod" >}}, {{< glossary_tooltip text="Services" term_id="service" >}}, and {{< glossary_tooltip text="StatefulSets" term_id="StatefulSet" >}}.
* 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 >}}
Please read the [setup](/docs/setup/) if you do not already have a cluster.
{{< /note >}}
### Additional Minikube Setup Instructions
### Additional Minikube setup instructions
{{< caution >}}
[Minikube](/docs/getting-started-guides/minikube/) defaults to 1024MB of memory and 1 CPU. Running Minikube with the default resource configuration results in insufficient resource errors during this tutorial. To avoid these errors, start Minikube with the following settings:
[Minikube](/docs/getting-started-guides/minikube/) defaults to 1024MiB of memory and 1 CPU. Running Minikube with the default resource configuration results in insufficient resource errors during this tutorial. To avoid these errors, start Minikube with the following settings:
```shell
minikube start --memory 5120 --cpus=4
```
{{< /caution >}}
{{% /capture %}}
{{% capture lessoncontent %}}
## Creating a Cassandra Headless Service
## Creating a headless Service for Cassandra {#creating-a-cassandra-headless-service}
A Kubernetes [Service](/docs/concepts/services-networking/service/) describes a set of [Pods](/docs/concepts/workloads/pods/pod/) that perform the same task.
In Kubernetes, a {{< glossary_tooltip text="Service" term_id="service" >}} describes a set of {{< glossary_tooltip text="Pods" term_id="pod" >}} that perform the same task.
The following `Service` is used for DNS lookups between Cassandra Pods and clients within the Kubernetes cluster.
The following Service is used for DNS lookups between Cassandra Pods and clients within your 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:
Create a Service to track all Cassandra StatefulSet members from the `cassandra-service.yaml` file:
```shell
kubectl apply -f https://k8s.io/examples/application/cassandra/cassandra-service.yaml
```
```shell
kubectl apply -f https://k8s.io/examples/application/cassandra/cassandra-service.yaml
```
### Validating (optional)
### Validating (optional) {#validating}
Get the Cassandra Service.
@ -94,9 +81,9 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
cassandra ClusterIP 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.
If you don't see a Service named `cassandra`, that means creation failed. Read [Debug Services](/docs/tasks/debug-application-cluster/debug-service/) for help troubleshooting common issues.
## Using a StatefulSet to Create a Cassandra Ring
## Using a StatefulSet to create a Cassandra ring
The StatefulSet manifest, included below, creates a Cassandra ring that consists of three Pods.
@ -106,14 +93,23 @@ This example uses the default provisioner for Minikube. Please update the follow
{{< codenew file="application/cassandra/cassandra-statefulset.yaml" >}}
1. Update the StatefulSet if necessary.
1. Create the Cassandra StatefulSet from the `cassandra-statefulset.yaml` file:
Create the Cassandra StatefulSet from the `cassandra-statefulset.yaml` file:
```shell
kubectl apply -f https://k8s.io/examples/application/cassandra/cassandra-statefulset.yaml
```
```shell
# Use this if you are able to apply cassandra-statefulset.yaml unmodified
kubectl apply -f https://k8s.io/examples/application/cassandra/cassandra-statefulset.yaml
```
## Validating The Cassandra StatefulSet
If you need to modify `cassandra-statefulset.yaml` to suit your cluster, download
https://k8s.io/examples/application/cassandra/cassandra-statefulset.yaml and then apply
that manifest, from the folder you saved the modified version into:
```shell
# Use this if you needed to modify cassandra-statefulset.yaml locally
kubectl apply -f cassandra-statefulset.yaml
```
## Validating the Cassandra StatefulSet
1. Get the Cassandra StatefulSet:
@ -121,31 +117,32 @@ This example uses the default provisioner for Minikube. Please update the follow
kubectl get statefulset cassandra
```
The response should be:
The response should be similar to:
```
NAME DESIRED CURRENT AGE
cassandra 3 0 13s
```
The `StatefulSet` resource deploys Pods sequentially.
The `StatefulSet` resource deploys Pods sequentially.
1. Get the Pods to see the ordered creation status:
```shell
kubectl get pods -l="app=cassandra"
```
The response should be:
The response should be similar to:
```shell
NAME READY STATUS RESTARTS AGE
cassandra-0 1/1 Running 0 1m
cassandra-1 0/1 ContainerCreating 0 8s
```
It can take several minutes for all three Pods to deploy. Once they are deployed, the same command returns:
It can take several minutes for all three Pods to deploy. Once they are deployed, the same command
returns output similar to:
```
NAME READY STATUS RESTARTS AGE
cassandra-0 1/1 Running 0 10m
@ -153,13 +150,14 @@ This example uses the default provisioner for Minikube. Please update the follow
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.
3. Run the Cassandra [nodetool](https://cwiki.apache.org/confluence/display/CASSANDRA2/NodeTool) inside the first Pod, to
display the status of the ring.
```shell
kubectl exec -it cassandra-0 -- nodetool status
```
The response should look something like this:
The response should look something like:
```
Datacenter: DC1-K8Demo
@ -174,7 +172,7 @@ This example uses the default provisioner for Minikube. Please update the follow
## Modifying the Cassandra StatefulSet
Use `kubectl edit` to modify the size of a Cassandra StatefulSet.
Use `kubectl edit` to modify the size of a Cassandra StatefulSet.
1. Run the following command:
@ -182,14 +180,14 @@ Use `kubectl edit` to modify the size of a Cassandra StatefulSet.
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:
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
apiVersion: apps/v1
kind: StatefulSet
metadata:
creationTimestamp: 2016-08-13T18:40:58Z
@ -204,50 +202,66 @@ Use `kubectl edit` to modify the size of a Cassandra StatefulSet.
replicas: 3
```
1. Change the number of replicas to 4, and then save the manifest.
1. Change the number of replicas to 4, and then save the manifest.
The `StatefulSet` now contains 4 Pods.
The StatefulSet now scales to run with 4 Pods.
1. Get the Cassandra StatefulSet to verify:
1. Get the Cassandra StatefulSet to verify your change:
```shell
kubectl get statefulset cassandra
```
The response should be
The response should be similar to:
```
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 setting is for your safety because your data is more valuable than automatically purging all related StatefulSet resources.
Deleting or scaling a StatefulSet down does not delete the volumes associated with the StatefulSet. This setting is for your safety because your data is more valuable than automatically purging all related StatefulSet resources.
{{< warning >}}
Depending on the storage class and reclaim policy, deleting the *PersistentVolumeClaims* 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`:
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}') \
grace=$(kubectl get pod cassandra-0 -o=jsonpath='{.spec.terminationGracePeriodSeconds}') \
&& kubectl delete statefulset -l app=cassandra \
&& echo "Sleeping $grace" \
&& echo "Sleeping ${grace} seconds" 1>&2 \
&& sleep $grace \
&& kubectl delete pvc -l app=cassandra
&& kubectl delete persistentvolumeclaim -l app=cassandra
```
1. Run the following command to delete the Cassandra Service.
1. Run the following command to delete the Service you set up for Cassandra:
```shell
kubectl delete service -l app=cassandra
```
{{% /capture %}}
## Cassandra container environment variables
The Pods 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`.
| Environment variable | Default value |
| ------------------------ |:---------------: |
| `CASSANDRA_CLUSTER_NAME` | `'Test Cluster'` |
| `CASSANDRA_NUM_TOKENS` | `32` |
| `CASSANDRA_RPC_ADDRESS` | `0.0.0.0` |
{{% /capture %}}
{{% capture whatsnext %}}
* Learn how to [Scale a StatefulSet](/docs/tasks/run-application/scale-stateful-set/).