DOCSEARCHbyAlgolia
Submit Docs

Cass Operator

repository·master·Indexed 42 days ago

https://github.com/k8ssandra/cass-operator

A Kubernetes operator for managing Apache Cassandra and DataStax Enterprise (DSE) clusters. It utilizes the CassandraDatacenter Custom Resource Definition (CRD) to manage cluster topology, scaling, and configuration, supporting versions such as Cassandra 3.11.6 through 3.11.7 and DSE 6.8.0 through 6.8.4.

Tokens
24.4K
Snippets
58
Records
80
Agent score
53%

What's inside Cass Operator

  1. Override container settings in CassandraDatacenter

    master

    You can override default container settings by providing a podTemplateSpec in your CassandraDatacenter resource.

    Supported Container Names:

    • server-config-init (Init Container)
    • cassandra (Main Container)
    • server-system-logger (Sidecar Container)

    User-specified environment variables, ports, and volumes are added to the values automatically generated by the operator. For example, to add an extra environment variable to the init container or change the termination message policy for the Cassandra container:

    spec:
  podTemplateSpec:
    spec:
      initContainers:
        - name: "server-config-init"
          env:
          - name: "EXTRA_PARAM"
            value: "123"
      containers:
        - name: "cassandra"
          terminationMessagePath: "/dev/other-termination-log"
          terminationMessagePolicy: "File"
    apiVersion: cassandra.datastax.com/v1beta1
kind: CassandraDatacenter
metadata:
  name: dc1
spec:
  clusterName: cluster1
  serverType: cassandra
  serverVersion: 3.11.11
  managementApiAuth:
    insecure: {}
  size: 3
  podTemplateSpec:
    spec:
      initContainers:
        - name: "server-config-init"
          env:
          - name: "EXTRA_PARAM"
            value: "123"
      containers:
        - name: "cassandra"
          terminationMessagePath: "/dev/other-termination-log"
          terminationMessagePolicy: "File"
  storageConfig:
    cassandraDataVolumeClaimSpec:
      storageClassName: server-storage
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 5Gi
  config:
    cassandra-yaml:
      authenticator: org.apache.cassandra.auth.PasswordAuthenticator
      authorizer: org.apache.cassandra.auth.CassandraAuthorizer
      role_manager: org.apache.cassandra.auth.CassandraRoleManager
    jvm-options:
      initial_heap_size: 800M
      max_heap_size: 800M

  2. Create a multi-datacenter cluster

    master

    To implement a multi-datacenter architecture within a single Kubernetes cluster, create two separate CassandraDatacenter resources and ensure they both share the exact same clusterName in their spec.

    # Datacenter 1
apiVersion: cassandra.cass-operator.k8s.io/v1alpha1
kind: CassandraDatacenter
metadata:
  name: dc1
spec:
  clusterName: my-multi-dc-cluster
---
# Datacenter 2
apiVersion: cassandra.cass-operator.k8s.io/v1alpha1
kind: CassandraDatacenter
metadata:
  name: dc2
spec:
  clusterName: my-multi-dc-cluster

  3. Understand encryption and keystores

    master

    The operator automates keystore and truststore creation for client-to-node and internode encryption.

    • Secret Injection: For every datacenter, credentials are injected into the StatefulSet via a secret named <datacenter-name>-keystore.
    • Usage: To enable encryption, reference these injected keystores in the cassandra parameters within your datacenter configuration.
    • Limitations: Current support focuses on internode encryption with CA-only verification. Peer name verification is not currently available via this method.
    • Rolling Updates: Changing from encrypted to unencrypted (or vice versa) is not supported as a rolling update; the entire cluster must be stopped and started.

  4. Configure the Cassandra database via the config key

    master

    The config key in the CassandraDatacenter resource is used to pass parameters to the server process.

    Do not repeat parameters that are already defined as top-level fields in the CassandraDatacenter resource, such as:

    • cluster_name (defined via spec.clusterName)
    • Rack and Datacenter properties

    Do not specify values that the operator automatically populates based on the environment, such as:

    • initial_token
    • listen_address or other IP addresses

    The config structure is designed to be compatible with the DataStax OpsCenter Lifecycle Manager (LCM) Configuration Profiles API.

  5. Deployment scope and configuration of cass-operator

    master

    The cass-operator is designed to be Namespace scoped. This allows a single Kubernetes cluster to run multiple instances of the operator in different namespaces, enabling the management of multiple independent Cassandra clusters and environments.

    Configuration is performed using YAML-based overrides within the Custom Resource, which are applied via an init container.

  6. How seed node labeling works in Cass Operator

    master

    The Cass Operator manages seed nodes declaratively by labeling pods. To ensure cluster stability, pods are only labeled as seeds after they are ready to service traffic.

    Key behaviors:

    • Automatic Selection: The operator automatically labels the lowest ordinal pod(s) in each StatefulSet as the seed nodes.
    • Resilience: If a seed pod dies, the operator will label a neighboring pod as a seed to maintain the seed count, bring the original seed pod back online, and then swap the seed label back to the original pod once it is healthy.
    • Exception: The only time pods are labeled as seeds before they are ready to service traffic is during a fresh cluster startup or during an 'unparking' operation.

  7. How cass-operator manages Cassandra clusters

    master

    The cass-operator is a modular operator designed to manage Apache Cassandra and its derived distributions (like DataStax Enterprise). It uses the CassandraDatacenter Custom Resource (CR) to manage the deployment of a Cassandra cluster around the logical domain of a datacenter.

    When you submit a CassandraDatacenter resource, the operator:

    1. Provisions Infrastructure: Handles the creation of underlying StatefulSets (which correspond to Cassandra logical racks), Services, and configurations.
    2. Manages Lifecycle: Monitors pod state via Kubernetes callbacks to perform day-to-day operations such as restarting failed processes, scaling clusters, and deploying configuration changes using a rolling, non-disruptive approach.
    3. Orchestrates Startup: Uses a sidecar process within the main container to manage the specific timing and ordering required to start the Cassandra process correctly and maintain even distribution across the cluster.

  8. How Cassandra clusters and datacenters are structured

    master

    The CassandraDatacenter is the primary resource managed by the operator. The relationship between these resources determines the cluster topology:

    • Single-Datacenter Cluster: Defined by a single CassandraDatacenter resource.
    • Multiple Unrelated Clusters: Multiple CassandraDatacenter resources in the same namespace, each with a different spec.clusterName.
    • Multi-Datacenter Cluster: Multiple CassandraDatacenter resources that share the same spec.clusterName. The operator joins these instances into a single logical topology.

  9. Security considerations for external access

    master

    Accessing Cassandra or DSE instances from CQL clients outside the Kubernetes cluster is considered an advanced topic.

    Warning: Exposing Cassandra or DSE to the public internet with default credentials or disabled authentication is extremely dangerous.

    Best Practices:

    • Protect the cluster with a network firewall during deployment.
    • Secure the default superuser account before exposing any ports publicly.

  10. Configure Rack topology and node affinity

    master

    Cassandra uses racks to define fault domains. In cloud environments, racks typically align with Availability Zones.

    Since version 1.6.0, the zone parameter is deprecated. Instead, use nodeAffinityLabels at both the datacenter (spec.nodeAffinityLabels) and rack (spec.racks[].nodeAffinityLabels) levels. These labels are a map of key/value pairs that are matched against Kubernetes worker node labels during scheduling.

    To find available labels on your nodes, use: kubectl get nodes <node_name> -o jsonpath={.metadata.labels}

    metadata:
  name: dc1
spec:
  clusterName: cluster1
  serverType: cassandra
  serverVersion: 3.11.7
  managementApiAuth:
    insecure: {}
  size: 3
  nodeAffinityLabels:
    dc: us-va
  racks:
  - name: r1
    nodeAffinityLabels:
      rack: us-va-1
  - name: r2
    nodeAffinityLabels:
      rack: us-va-2
  - name: r3
    nodeAffinityLabels:
      rack: us-va-3

  11. Configure node count and worker constraints

    master

    The size parameter defines the number of nodes in a datacenter.

    Important: By default, the operator recommends running only one server instance per Kubernetes worker node. If you have fewer worker nodes than the size value, pods will remain in a Pending status.

    To run multiple Cassandra nodes on a single worker (e.g., in a local minikube setup), you must set the allowMultipleNodesPerWorker parameter to true.

  12. How the validating webhook works in cass-operator

    master

    The cass-operator provides a validating webhook to enforce CRD-specific guardrails that standard Kubernetes schema validation cannot catch. This prevents invalid operations, such as renaming core identity elements like the cassandra cluster name or racks during an update or create request.

    To function correctly in Kubernetes, the webhook adheres to these requirements:

    • It is served over TLS.
    • The TLS service name must match the certificate subject.
    • The signing CA must be available to the kube-apiserver or explicitly configured in the ValidatingWebhookConfiguration object.

    The operator automates certificate management by using cert-manager to generate and inject the necessary certificates.