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

Merge pull request #9196 from lucperkins/lperkins/issue-8639-cassandra-pods 

Small fixes for Cassandra doc
pull/9678/head
Luc Perkins 2018-07-30 09:07:41 -07:00 committed by GitHub
parent 0edcf1972c 5dc61780fe
commit e1087b52d0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 142 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
assets/sass/styles.sass
View File

@ -4,4 +4,4 @@
// media queries
@import "base"
@import "tablet"
@import "desktop"
@import "desktop"

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

@ -7,44 +7,45 @@ weight: 30
---
{{% capture overview %}}
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.
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.
Deploying stateful distributed applications, like Cassandra, within a clustered environment can be challenging. StatefulSets greatly simplify this process. Please read about [StatefulSets](/docs/concepts/workloads/controllers/statefulset/) for more information about the features used in this tutorial.
`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 Docker**
**Cassandra on Docker**
The Pods use the [`gcr.io/google-samples/cassandra:v13`](https://github.com/kubernetes/examples/blob/master/cassandra/image/Dockerfile)
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)
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 |
| `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 [Services](/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 [`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 [Pods](/docs/concepts/workloads/pods/pod/), [Services](/docs/concepts/services-networking/service/), and [StatefulSets](/docs/concepts/workloads/controllers/statefulset/). In addition, you should:
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
* [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)
* 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
* 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.
@ -53,206 +54,206 @@ To complete this tutorial, you should already have a basic familiarity with [Pod
### Additional Minikube Setup Instructions
{{< caution >}}
**Caution:** [Minikube](/docs/getting-started-guides/minikube/) defaults to 1024MB of memory and 1 CPU which results in an insufficient resource errors during this tutorial.
**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 >}}
To avoid these errors, run minikube with:
minikube start --memory 5120 --cpus=4
{{% /capture %}}
{{% capture lessoncontent %}}
## 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.
The following `Service` is used for DNS lookups between Cassandra Pods and clients within the Kubernetes Cluster.
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:
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
```
```shell
kubectl create -f https://k8s.io/examples/application/cassandra/cassandra-service.yaml
```
### Validating (optional)
Get the Cassandra `Service`.
kubectl get svc cassandra
```shell
kubectl get svc cassandra
```
The response should be
The response is
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
cassandra None <none> 9042/TCP 45s
```
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
cassandra None <none> 9042/TCP 45s
```
If anything else returns, the service was not successfully created. Read [Debug Services](/docs/tasks/debug-application-cluster/debug-service/) for common issues.
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 Pods.
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:** 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:
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
```
```shell
kubectl create -f https://k8s.io/examples/application/cassandra/cassandra-statefulset.yaml
```
## Validating The Cassandra StatefulSet
1. Get the Cassandra StatefulSet:
1. Get the Cassandra `StatefulSet`:
```
kubectl get statefulset cassandra
```
```shell
kubectl get statefulset cassandra
```
The response should be
The response should be:
```
NAME DESIRED CURRENT AGE
cassandra 3 0 13s
```
```
NAME DESIRED CURRENT AGE
cassandra 3 0 13s
```
The StatefulSet resource deploys Pods sequentially.
The `StatefulSet` resource deploys `Pod`s sequentially.
1. Get the Pods to see the ordered creation status:
1. Get the `Pod`s to see the ordered creation status:
```shell
kubectl get pods -l="app=cassandra"
```
```shell
kubectl get pods -l="app=cassandra"
```
The response should be
The response should be:
```shell
NAME READY STATUS RESTARTS AGE
cassandra-0 1/1 Running 0 1m
cassandra-1 0/1 ContainerCreating 0 8s
```
```
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:
**Note:** It can take up to ten minutes for all three Pods to deploy.
```
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
```
Once all Pods are deployed, the same command returns:
3. Run the Cassandra [nodetool](https://wiki.apache.org/cassandra/NodeTool) to display the status of the ring.
```
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
```
```shell
kubectl exec -it cassandra-0 -- nodetool status
```
1. Run the Cassandra utility nodetool to display the status of the ring.
The response should look something like this:
```shell
kubectl exec cassandra-0 -- nodetool status
```
The response is:
```
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
```
```
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.
Use `kubectl edit` to modify the size of a Cassandra `StatefulSet`.
1. Run the following command:
```
kubectl edit statefulset cassandra
```
```shell
kubectl edit statefulset cassandra
```
This command opens an editor in your terminal. The line you need to change is the `replicas` field.
**Note:** 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:
```
# 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
```
```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
```
1. Change the number of replicas to 4, and then save the manifest.
2. Change the number of replicas to 4, and then save the manifest.
The StatefulSet now contains 4 Pods.
The `StatefulSet` now contains 4 `Pod`s.
1. Get the Cassandra StatefulSet to verify:
1. Get the Cassandra `StatefulSet` to verify:
```shell
kubectl get statefulset cassandra
```
```shell
kubectl get statefulset cassandra
```
The response should be
The response should be
```
NAME DESIRED CURRENT AGE
cassandra 4 4 36m
```
```
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.
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 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.
**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 to delete everything in a `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}') \
&& kubectl delete statefulset -l app=cassandra \
&& echo "Sleeping $grace" \
&& sleep $grace \
&& kubectl delete pvc -l app=cassandra
```
```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`.
```
kubectl delete service -l app=cassandra
```
```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)
* 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 %}}