Use Cassandra or DSE in Kubernetes with the Kubernetes Operator for Apache Cassandra

This topic explains how to use your configured and provisioned Apache Cassandra® or DSE cluster in Kubernetes.

Prerequisites

Create a Kubernetes cluster where you will set up the Cassandra Operator and Cassandra/DSE resources.
Authorize connections between your local machine where you will run kubectl commands and your Kubernetes cluster, as explained in Create a Kubernetes cluster.
Application of the example Cassandra Operator configuration, as shown in Configure Cassandra or DSE in Kubernetes with the Cassandra Operator.
Successful completion of the steps to provision and deploy a Cassandra or DSE cluster in your existing Kubernetes environment.

Connecting from inside the Kubernetes cluster

For an example of invoking cqlsh from inside a Kubernetes cluster, refer to Connect to Cassandra using CQL shell within Kubernetes Cluster.

The Cassandra Operator makes a Kubernetes headless service available at <clusterName>-<datacenterName>-service Any client app that submits CQL commands inside the Kubernetes cluster needs to connect to this service and use the nodes in a round-robin fashion as contact points.

When you use the Cassandra Java driver in an app, and prepare to connect the driver to a DSE cluster from within the Kubernetes cluster, there are two overall choices. The Java driver accepts either of the following:

Multiple Inet[Socket]Address parameters to connect.
One Inet[Socket]Address parameter to connect. In this case, the Java driver uses it as the cluster control connection, and then discovers other nodes through this connection.

However, in the Java driver 4.x series, when you specify a hostname in the contact points definition in the config file, the Java driver first resolves every host associated with the hostname. In the case of the cluster deployed by the the Cassandra Operator, using the hostname of the Kubernetes service (example: cluster1-dc1-service) resolves to every IP address associated with the DSE cluster; that is, all of the IPs of the DSE nodes. The Java driver chooses one of those nodes as the control connection, connects to the other resolved nodes, and performs cluster verification to all of its connected local DSE nodes.

For example, if you are programmatically configuring the Java driver, your app can use one of the following:

InetAddress.getByName(cluster1-dc1-service) to resolve only one host, which the driver uses at init time, and then connect to DSE to discover the rest of the nodes.
InetAddress.getAllByName(cluster1-dc1-service), which resolves all the nodes directly. The driver uses this setting as if you specified the multiple IP addresses of the nodes in the contact points.

Connecting from outside the Kubernetes cluster

When applications run within a Kubernetes cluster, you must access those services from outside the cluster. Connecting to a Cassandra cluster running within Kubernetes can range from trivial to complex, and is dependent on where the client is running, on latency requirements, and on security requirements. See Connect to Cassandra and apps from outside the Kubernetes cluster.

Scaling up the datacenter

The size parameter on the CassandraDatacenter determines how many Cassandra or DSE instances are present in the datacenter.

To add more nodes, edit the YAML file as described in Define the node count parameters. Then, reapply the CassandraDatacenter configuration:

kubectl -n my-db-ns apply -f ./cluster1-dc1.yaml

When you reapply the YAML configuration file with the additional nodes defined, the Cassandra Operator restarts and Kubernetes adds the pods to your datacenter, provided there are sufficient Kubernetes worker nodes available.

As part of the scaling up process, each rack in the Kubernetes cluster must contain the same number of server instances.

Changing the server configuration

To change the Cassandra or DSE configuration, update the CassandraDatacenter parameter and edit the config section of the spec key. Then, reapply the CassandraDatacenter configuration:

kubectl -n my-db-ns apply -f ./cluster1-dc1.yaml

The Cassandra Operator updates the configuration and restarts one node at a time in a rolling fashion.

Establishing a multi-datacenter cluster

Cassandra Operator doesn’t support multi-region clusters and advanced workloads. Many multi-datacenter use cases are inappropriate for Cassandra Operator.

To make a multi-datacenter cluster, create two CassandraDatacenter resources in the spec and give them the same clusterName.

Using `kubectl` to monitor resources in the Kubernetes cluster

Use kubectl commands to get more information about the Cassandra or DSE pods running in the Kubernetes cluster.

To get information about ongoing or recent events:
```
kubectl get event --all-namespaces
```
By default, Kubernetes configures each event with a one-hour Time to Live (TTL).

To check for errors in the Kubernetes log for your Cassandra Operator instance:

Get the instance name by using the kubectl get pod command and specifying your namespace. For example:

kubectl -n my-db-ns get pod

Sample output:

NAME                            READY   STATUS    RESTARTS   AGE
cass-operator-f74447c57-kdf2p   1/1     Running   0          13m
gke-cluster1-dc1-r1-sts-0       1/1     Running   0          5m38s
gke-cluster1-dc1-r2-sts-0       1/1     Running   0          42s
gke-cluster1-dc1-r3-sts-0       1/1     Running   0          6m7s

Then, use kubectl logs.

Because the log entries can be large, this example writes the output to a file:

kubectl -n my-db-ns logs cass-operator-f74447c57-kdf2p > ~/cass-operator-log.txt

To tail the Cassandra or DSE logs:

kubectl -n my-db-ns logs --container server-system-logger --follow gke-cluster1-dc1-r1-sts-0

Use the kubectl describe pod command to get identifying information about your pod. For example:

kubectl -n my-db-ns describe pod cass-operator-f74447c57-kdf2p