Was this page helpful?
Caution
You're viewing documentation for an unstable version of ScyllaDB Operator. Switch to the latest stable version.
ScyllaClusters¶
Introduction¶
ScyllaCluster defines a ScyllaDB datacenter and manages the racks within. This section aims to make you familiar with how it looks like and how to perform some of the basic configuration or accessing the APIs. By no means is this a complete description of what it can do. Please consult our generated API reference for a complete list of options.
Tip
You can always see the currently supported API fields for a particular version installed in your cluster by running
kubectl explain --api-version='scylla.scylladb.com/v1' ScyllaCluster.spec
Note that the Kubernetes clusters are only a regional concept, availability-wise they map into a ScyllaDB datacenter. To deploy a ScyllaDB cluster with multiple datacenters use our multi datacenter resource ScyllaDBCluster, or combine multiple Kubernetes clusters, each running a ScyllaCluster, To learn more about manual multi-dc deployments using ScyllaCluster resource, please see the dedicated multi-datacenter guide.
Creating a ScyllaCluster¶
Before we go and create the ScyllaCluster, we’ll first create our ScyllaDB config file that we’ll reference later in the ScyllaCluster definition.
1kubectl apply --server-side -f=- <<EOF
2apiVersion: v1
3kind: ConfigMap
4metadata:
5 name: scylladb-config
6data:
7 scylla.yaml: |
8 authenticator: PasswordAuthenticator
9 authorizer: CassandraAuthorizer
10 # Other options
11EOF
Note
Some of the ScyllaDB config is also generated by the ScyllaDB Operator based on your ScyllaCluster definition. While you shall not define conflicting options here (ScyllaDB Operator config wins), we still want to give you a reasonable control to fine tune some ScyllaDB knobs. IOW, please stay away from touching networking, listen or published addresses and so on, but feel free to tune buffer sizes and such.
Now we can create a simple ScyllaCluster to get ScyllaDB running.
Warning
To ensure high availability and fault tolerance in ScyllaDB, it is crucial to spread your nodes across multiple racks or availability zones. As a general rule of thumb, you should use as many racks as your desired replication factor.
For example, if your replication factor is 3, deploy your nodes across 3 different racks or availability zones. This minimizes the risk of data loss and ensures your cluster remains available even if an entire rack or zone fails.
kubectl apply --server-side -f=- <<EOF
apiVersion: scylla.scylladb.com/v1
kind: ScyllaCluster
metadata:
name: scylladb
spec:
repository: docker.io/scylladb/scylla
version: 2025.4.3
agentVersion: 3.8.0
developerMode: false
automaticOrphanedNodeCleanup: true
datacenter:
name: us-east-1
racks:
- name: us-east-1a
members: 1
scyllaConfig: scylladb-config
storage:
capacity: 100Gi
storageClassName: scylladb-local-xfs
resources:
requests:
cpu: 1
memory: 8Gi
limits:
cpu: 1
memory: 8Gi
agentResources:
requests:
cpu: 100m
memory: 100Mi
limits:
cpu: 100m
memory: 100Mi
placement:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: topology.kubernetes.io/zone
operator: In
values:
- us-east-1a
- key: scylla.scylladb.com/node-type
operator: In
values:
- scylla
tolerations:
- key: scylla-operator.scylladb.com/dedicated
operator: Equal
value: scyllaclusters
effect: NoSchedule
- name: us-east-1b
members: 1
scyllaConfig: scylladb-config
storage:
capacity: 100Gi
storageClassName: scylladb-local-xfs
resources:
requests:
cpu: 1
memory: 8Gi
limits:
cpu: 1
memory: 8Gi
agentResources:
requests:
cpu: 100m
memory: 100Mi
limits:
cpu: 100m
memory: 100Mi
placement:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: topology.kubernetes.io/zone
operator: In
values:
- us-east-1b
- key: scylla.scylladb.com/node-type
operator: In
values:
- scylla
tolerations:
- key: scylla-operator.scylladb.com/dedicated
operator: Equal
value: scyllaclusters
effect: NoSchedule
- name: us-east-1c
members: 1
scyllaConfig: scylladb-config
storage:
capacity: 100Gi
storageClassName: scylladb-local-xfs
resources:
requests:
cpu: 1
memory: 8Gi
limits:
cpu: 1
memory: 8Gi
agentResources:
requests:
cpu: 100m
memory: 100Mi
limits:
cpu: 100m
memory: 100Mi
placement:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: topology.kubernetes.io/zone
operator: In
values:
- us-east-1c
- key: scylla.scylladb.com/node-type
operator: In
values:
- scylla
tolerations:
- key: scylla-operator.scylladb.com/dedicated
operator: Equal
value: scyllaclusters
effect: NoSchedule
EOF
Note
Values in these examples are only illustratory. You should always adjust the resources and storage capacity depending on your needs or the size and the type of your Kubernetes nodes. Similarly, the tolerations will differ depending on how and whether you set up dedicated node pools, or the placement if you want to set affinity for your rack to an availability zone or a failure domain.
Caution
Only Pods with Guaranteed QoS class are eligible to be tuned, otherwise they would not have pinned CPUs.
Always verify that your ScyllaCluster resource specifications meat all the criteria.
Don’t forget you have to specify limits for both resources(ScyllaDB) and agentResources(ScyllaDB Manager Agent) that run in the same Pod.
Note
ScyllaDB Operator works with both ScyllaDB Open Source and ScyllaDB Enterprise. You only have to adjust the repository and tag fields for each ScyllaCluster.
In addition to it, if you want to use tuning from the Enterprise repository, you have to adjust scyllaUtilsImage on the global ScyllaOperatorConfig/cluster.
1apiVersion: scylla.scylladb.com/v1
2kind: ScyllaCluster
3metadata:
4 name: scylladb
5spec:
6 repository: docker.io/scylladb/scylla-enterprise
7 version: 2025.4.3
8 # ...
9EOF
Wait for it to deploy by watching status conditions.
kubectl wait --for='condition=Progressing=False' scyllacluster.scylla.scylladb.com/scylladb
kubectl wait --for='condition=Degraded=False' scyllacluster.scylla.scylladb.com/scylladb
kubectl wait --for='condition=Available=True' scyllacluster.scylla.scylladb.com/scylladb
IPv6 and Dual-Stack Networking¶
You can run ScyllaDB clusters on IPv6-only networks or use both IPv4 and IPv6 together (dual-stack).
IPv6 Configuration¶
Configure IPv6 using the network field to specify which IP version ScyllaDB should use:
apiVersion: scylla.scylladb.com/v1
kind: ScyllaCluster
metadata:
name: scylla-ipv6
spec:
version: {{scyllaDBImageTag}}
network:
ipFamilies:
- IPv6
ipFamilyPolicy: SingleStack
dnsPolicy: ClusterFirst
datacenter:
name: dc1
racks:
- name: rack1
members: 3
storage:
capacity: 10Gi
resources:
requests:
cpu: 1
memory: 4Gi
exposeOptions:
broadcastOptions:
nodes:
type: PodIP
clients:
type: PodIP
Dual-Stack Configuration¶
For dual-stack environments (both IPv4 and IPv6), specify both IP families with the primary one first:
apiVersion: scylla.scylladb.com/v1
kind: ScyllaCluster
metadata:
name: scylla-dual-stack
spec:
version: {{scyllaDBImageTag}}
network:
ipFamilies:
- IPv4
- IPv6
ipFamilyPolicy: PreferDualStack
dnsPolicy: ClusterFirst
datacenter:
name: dc1
racks:
- name: rack1
members: 3
storage:
capacity: 10Gi
resources:
requests:
cpu: 1
memory: 4Gi
exposeOptions:
broadcastOptions:
nodes:
type: PodIP
clients:
type: PodIP
What happens by default¶
Important
DNS Configuration for IPv6
When using IPv6, it’s recommended to explicitly set dnsPolicy: ClusterFirst in the network configuration:
spec:
network:
dnsPolicy: ClusterFirst
This will make sure proper IPv6 DNS resolution within the Kubernetes cluster, which is essential for ScyllaDB nodes to discover each other using IPv6 addresses.
Important
If you don’t specify IP families, ScyllaCluster will use IPv4 by default:
IPv4-only clusters: Uses IPv4 (default behavior)
IPv6-only clusters: Set
network.ipFamilies: [IPv6]Dual-stack clusters: Set both families with primary first, e.g.,
network.ipFamilies: [IPv4, IPv6]
This means existing clusters keep working without any changes.
Configuration Options¶
Field |
What it does |
Default |
Required? |
|---|---|---|---|
|
IP versions for ScyllaDB and services (first is primary) |
|
Recommended for IPv6 |
|
How services handle IP versions |
|
Only for advanced dual-stack |
Note
When do you need explicit network configuration?
IPv6-only: Set
network.ipFamilies: [IPv6]andnetwork.ipFamilyPolicy: SingleStackDual-stack: Set
network.ipFamilies: [IPv4, IPv6](or reverse order) andnetwork.ipFamilyPolicy: PreferDualStackIPv4-only (default): No configuration needed
For detailed configuration, troubleshooting, and examples, see the IPv6 networking documentation.
Forcing a rolling restart¶
When you change a ScyllaDB config option that’s not live reloaded by ScyllaDB, or want to trigger a rolling restart for a different reason, ScyllaCluster allows triggering the rolling restarts declaratively by changing ScyllaCluster.spec.forceRedeploymentReason to any other value. This will trigger a rolling restart of all ScyllaDB nodes in sequence, always respecting the PodDistruptionsBudget and keeping the cluster available.
Spreading racks over availability zones¶
ScyllaCluster give you the freedom to chose how you want to spread you rack over your Kubernetes nodes with generic placement options. Here is a quick example of how you’d use them to spread your racks across different availability zone:
Warning
To ensure high availability and fault tolerance in ScyllaDB, it is crucial to spread your nodes across multiple racks or availability zones. As a general rule of thumb, you should use as many racks as your desired replication factor.
For example, if your replication factor is 3, deploy your nodes across 3 different racks or availability zones. This minimizes the risk of data loss and ensures your cluster remains available even if an entire rack or zone fails.
spec:
datacenter:
name: <dc_name>
racks:
- name: <rack_name>
placement:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: failure-domain.beta.kubernetes.io/zone
operator: In
values:
- <gcp_zone>
spec:
datacenter:
name: <dc_name>
racks:
- name: <rack_name>
placement:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: topology.kubernetes.io/zone
operator: In
values:
- <aws_zone>
Next steps¶
To follow up with other advanced topics, see the section index for options.