Merge pull request #17995 from sftim/20191208_update_cassandra_statefulset_tutorial

k8s-ci-robot · web-flow · commit 26d14b6b566b · 2020-04-06T05:49:46.000-07:00
Update Cassandra StatefulSet tutorial
diff --git a/content/en/docs/tutorials/stateful-application/cassandra.md b/content/en/docs/tutorials/stateful-application/cassandra.md
@@ -1,85 +1,72 @@
 ---
-title: "Example: Deploying Cassandra with Stateful Sets"
+title: "Example: Deploying Cassandra with a StatefulSet"
 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.
+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.
-
-**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`          |
+*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/).
 
+{{< 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:
-
-* [Install and Configure](/docs/tasks/tools/install-kubectl/) the *kubectl* command-line tool
+{{< include "task-tutorial-prereqs.md" >}}
 
-* Download [`cassandra-service.yaml`](/examples/application/cassandra/cassandra-service.yaml)
-  and [`cassandra-statefulset.yaml`](/examples/application/cassandra/cassandra-statefulset.yaml)
+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" >}}.
 
-* 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,60 +93,71 @@ 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
+```
+
+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
+
+## Validating the Cassandra StatefulSet
 
 1. Get the Cassandra StatefulSet:
 
     ```shell
     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
     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.
+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,22 +172,22 @@ 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:
 
     ```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:
+    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/).
