Merge pull request #17995 from sftim/20191208_update_cassandra_statefulset_tutorial
Update Cassandra StatefulSet tutorialpull/20135/head
Kubernetes Prow Robot
GitHub
commit
26d14b6b56
|
|
@ -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,54 +7,41 @@ 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
|
||||
|
|
@ -64,22 +51,22 @@ minikube start --memory 5120 --cpus=4
|
|||
{{% /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,7 +117,7 @@ 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
|
||||
|
|
@ -136,7 +132,7 @@ This example uses the default provisioner for Minikube. Please update the follow
|
|||
kubectl get pods -l="app=cassandra"
|
||||
```
|
||||
|
||||
The response should be:
|
||||
The response should be similar to:
|
||||
|
||||
```shell
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
|
|
@ -144,7 +140,8 @@ This example uses the default provisioner for Minikube. Please update the follow
|
|||
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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -206,15 +204,15 @@ Use `kubectl edit` to modify the size of a Cassandra StatefulSet.
|
|||
|
||||
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
|
||||
|
|
@ -230,24 +228,40 @@ Deleting or scaling a StatefulSet down does not delete the volumes associated wi
|
|||
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/).
|
||||
|
|
|
|||
Loading…
Reference in New Issue