Cassandra operator

Build Test

Project status: alpha

Major planned features have yet to be completed and API changes are currently planned, we reserve the right to address bugs and API changes in a backwards incompatible way before the project is declared stable. See upgrade guide for safe upgrade process.

Currently user facing Cassandra cluster objects are created as Kubernetes Custom Resources, however, taking advantage of User Aggregated API Servers to improve reliability, validation and versioning may be undertaken. The use of Aggregated API should be minimally disruptive to existing users but may change what Kubernetes objects are created or how users deploy the operator.

We expect to consider the Cassandra operator stable soon; backwards incompatible changes will not be made once the project reaches stability.

Overview

The Cassandra operator manages Cassandra clusters deployed to Kubernetes and automates tasks related to operating an Cassandra cluster.

Create and destroy
Resize
Recover a member
Backup and restore a cluster
Rolling upgrade

There are more spec examples on setting up clusters with backup, restore, and other configurations.

Read Best Practices for more information on how to better use Cassandra operator.

Read RBAC docs for how to setup RBAC rules for Cassandra operator if RBAC is in place.

Read Developer Guide for setting up development environment if you want to contribute.

See the Resources and Labels doc for an overview of the resources created by the Cassandra-operator.

Requirements

Kubernetes 1.7+
Cassandra 3.11+

Deploy Cassandra operator

See instructions on how to install/uninstall Cassandra operator .

Create and destroy an Cassandra cluster

$ kubectl create -f example/example-cassandra-cluster.yaml

A 3 member Cassandra cluster will be created.

$ kubectl get pods
NAME                            READY     STATUS    RESTARTS   AGE
example-cassandra-cluster-0000       1/1       Running   0          1m
example-cassandra-cluster-0001       1/1       Running   0          1m
example-cassandra-cluster-0002       1/1       Running   0          1m

See client service for how to access Cassandra clusters created by operator.

Destroy Cassandra cluster:

$ kubectl delete -f example/example-Cassandra-cluster.yaml

Resize an Cassandra cluster

Create an Cassandra cluster:

$ kubectl apply -f example/example-Cassandra-cluster.yaml

In example/example-Cassandra-cluster.yaml the initial cluster size is 3. Modify the file and change size from 3 to 5.

$ cat example/example-Cassandra-cluster.yaml
apiVersion: "cassandra.database.instaclustr.com/v1beta2"
kind: "CassandraCluster"
metadata:
  name: "example-cassandra-cluster"
spec:
  size: 5
  version: "3.11.0"

Apply the size change to the cluster CR:

$ kubectl apply -f example/example-cassandra-cluster.yaml

The Cassandra cluster will scale to 5 members (5 pods):

$ kubectl get pods
NAME                            READY     STATUS    RESTARTS   AGE
example-cassandra-cluster-0000       1/1       Running   0          1m
example-cassandra-cluster-0001       1/1       Running   0          1m
example-cassandra-cluster-0002       1/1       Running   0          1m
example-cassandra-cluster-0003       1/1       Running   0          1m
example-cassandra-cluster-0004       1/1       Running   0          1m

Similarly we can decrease the size of cluster from 5 back to 3 by changing the size field again and reapplying the change.

$ cat example/example-Cassandra-cluster.yaml
apiVersion: "cassandra.database.instaclustr.com/v1beta2"
kind: "cassandraCluster"
metadata:
  name: "example-cassandra-cluster"
spec:
  size: 3
  version: "3.11.0"

$ kubectl apply -f example/example-cassandra-cluster.yaml

We should see that Cassandra cluster will eventually reduce to 3 pods:

$ kubectl get pods
NAME                            READY     STATUS    RESTARTS   AGE
example-cassandra-cluster-0002       1/1       Running   0          1m
example-cassandra-cluster-0003       1/1       Running   0          1m
example-cassandra-cluster-0004       1/1       Running   0          1m

Member recovery

If the minority of Cassandra members crash, the Cassandra operator will automatically recover the failure. Let's walk through in the following steps.

Create an Cassandra cluster:

$ kubectl create -f example/example-cassandra-cluster.yaml

Wait until all three members are up. Simulate a member failure by deleting a pod:

$ kubectl delete pod example-Cassandra-cluster-0000 --now

The Cassandra operator will recover the failure by creating a new pod example-cassandra-cluster-0003:

$ kubectl get pods
NAME                            READY     STATUS    RESTARTS   AGE
example-cassandra-cluster-0001       1/1       Running   0          1m
example-cassandra-cluster-0002       1/1       Running   0          1m
example-cassandra-cluster-0003       1/1       Running   0          1m

Destroy Cassandra cluster:

$ kubectl delete -f example/example-cassandra-cluster.yaml