scylladb · ylebi · Sep 15, 2025
diff --git a/assets/scylladb/managedconfig.cm.yaml b/assets/scylladb/managedconfig.cm.yaml
@@ -6,7 +6,33 @@ metadata:
 data:
   {{ .ManagedConfigName | printf "%q" }}: |
     cluster_name: "{{ .ClusterName }}"
+    {{- if .Spec.IPFamily }}
+    {{- if eq (deref .Spec.IPFamily) "IPv6" }}
+    rpc_address: "::"
+    api_address: "::1"
+    listen_address: "::"
+    seed_provider:
+      - class_name: org.apache.cassandra.locator.SimpleSeedProvider
+        parameters:
+          - seeds: "::1"
+    {{- else }}    
     rpc_address: "0.0.0.0"
+    api_address: "127.0.0.1"
+    listen_address: "0.0.0.0"
+    seed_provider:
+      - class_name: org.apache.cassandra.locator.SimpleSeedProvider
+        parameters:
+          - seeds: "127.0.0.1"
+    {{- end }}
+    {{- else }}
+    rpc_address: "0.0.0.0"
+    api_address: "127.0.0.1"
+    listen_address: "0.0.0.0"
+    seed_provider:
+      - class_name: org.apache.cassandra.locator.SimpleSeedProvider
+        parameters:
+          - seeds: "127.0.0.1"
+    {{- end }}
     endpoint_snitch: "GossipingPropertyFileSnitch"
     internode_compression: "all"
 

diff --git a/assets/scylladb/registry.go b/assets/scylladb/registry.go
@@ -26,4 +26,10 @@ var (
 	ScyllaDBSnitchConfigTemplate       = lazy.New(func() *assets.ObjectTemplate[*corev1.ConfigMap] {
 		return ParseObjectTemplateOrDie[*corev1.ConfigMap]("scylladb-snitch-config", scyllaDBSnitchConfigTemplateString)
 	})
+
+	//go:embed "scylla-manager-agent-config.cm.yaml"
+	scyllaDBManagerAgentConfigTemplateString string
+	ScyllaDBManagerAgentConfigTemplate       = lazy.New(func() *assets.ObjectTemplate[*corev1.ConfigMap] {
+		return ParseObjectTemplateOrDie[*corev1.ConfigMap]("scylladb-manager-agent-config", scyllaDBManagerAgentConfigTemplateString)
+	})
 )
diff --git a/assets/scylladb/scylla-manager-agent-config.cm.yaml b/assets/scylladb/scylla-manager-agent-config.cm.yaml
@@ -0,0 +1,26 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  namespace: "{{ .Namespace }}"
+  name: "{{ .Name }}"
+data:
+  {{ .ScyllaAgentConfigFileName | printf "%q" }}: |
+    # ScyllaDB API endpoint configuration based on IP family
+    {{- if .Spec.IPFamily }}
+    {{- if eq (deref .Spec.IPFamily) "IPv6" }}
+    scylla:
+      api_address: "::1"
+      api_port: 10000
+    {{- else }}
+    scylla:
+      api_address: "127.0.0.1"
+      api_port: 10000
+    {{- end }}
+    {{- else }}
+    scylla:
+      api_address: "127.0.0.1"
+      api_port: 10000
+    {{- end }}
+
+    # Default ScyllaDB Manager Agent configuration
+    # Additional configuration can be provided via customConfigSecretRef
diff --git a/bundle/manifests/scylla.scylladb.com_scyllaclusters.yaml b/bundle/manifests/scylla.scylladb.com_scyllaclusters.yaml
@@ -3650,6 +3650,15 @@ spec:
                   type: object
                   x-kubernetes-map-type: atomic
                 type: array
+              ipFamily:
+                default: IPv4
+                description: |-
+                  IPFamily specifies the IP family for this cluster.
+                  All services, broadcast addresses, and pod IPs will use this IP family.
+                enum:
+                - IPv4
+                - IPv6
+                type: string
               minReadySeconds:
                 description: |-
                   minReadySeconds is the minimum number of seconds for which a newly created ScyllaDB node should be ready
@@ -3682,6 +3691,22 @@ spec:
                       avoids going through Kubernetes SDN and exposes scylla on node's IP.
                       Deprecated: `hostNetworking` is deprecated and may be ignored in the future.
                     type: boolean
+                  ipFamilies:
+                    description: |-
+                      ipFamilies specifies the IP families to use.
+                      Supports: IPv4, IPv6.
+                    items:
+                      description: |-
+                        IPFamily represents the IP Family (IPv4 or IPv6). This type is used
+                        to express the family of an IP expressed by a type (e.g. service.spec.ipFamilies).
+                      type: string
+                    type: array
+                  ipFamilyPolicy:
+                    default: SingleStack
+                    description: |-
+                      ipFamilyPolicy specifies the IP family policy for the cluster.
+                      Supports: SingleStack, PreferDualStack, RequireDualStack.
+                    type: string
                 type: object
               podMetadata:
                 description: podMetadata controls shared metadata for all pods created

diff --git a/bundle/manifests/scylla.scylladb.com_scylladbdatacenters.yaml b/bundle/manifests/scylla.scylladb.com_scylladbdatacenters.yaml
@@ -223,6 +223,15 @@ spec:
                   type: object
                   x-kubernetes-map-type: atomic
                 type: array
+              ipFamily:
+                default: IPv4
+                description: |-
+                  IPFamily specifies the IP family for this datacenter.
+                  All services, broadcast addresses, and pod IPs will use this IP family.
+                enum:
+                - IPv4
+                - IPv6
+                type: string
               metadata:
                 description: metadata controls shared metadata for all pods created
                   based on this spec.

diff --git a/deploy/operator.yaml b/deploy/operator.yaml
diff --git a/docs/source/api-reference/groups/scylla.scylladb.com/scyllaclusters.rst b/docs/source/api-reference/groups/scylla.scylladb.com/scyllaclusters.rst
diff --git a/docs/source/api-reference/groups/scylla.scylladb.com/scylladbdatacenters.rst b/docs/source/api-reference/groups/scylla.scylladb.com/scylladbdatacenters.rst
diff --git a/docs/source/resources/scyllaclusters/basics.md b/docs/source/resources/scyllaclusters/basics.md
@@ -201,6 +201,157 @@ Wait for it to deploy by watching status conditions.
 :::{include} ./../../.internal/wait-for-status-conditions.scyllacluster.code-block.md
 :::
 
+## 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
+
+Use the `ipFamily` field to specify which IP version ScyllaDB should use:
+
+```yaml
+apiVersion: scylla.scylladb.com/v1
+kind: ScyllaCluster
+metadata:
+  name: scylla-ipv6
+spec:
+  version: {{imageTag}}
+  ipFamily: IPv6
+
+  network:
+    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), you typically only need to specify the IP family for ScyllaDB:
+
+```yaml
+apiVersion: scylla.scylladb.com/v1
+kind: ScyllaCluster
+metadata:
+  name: scylla-dual-stack
+spec:
+  version: {{imageTag}}
+  ipFamily: IPv4
+
+  network:
+    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
+```
+
+**Advanced**: If you need explicit control over service networking, you can configure it manually:
+
+```yaml
+apiVersion: scylla.scylladb.com/v1
+kind: ScyllaCluster
+metadata:
+  name: scylla-dual-stack-explicit
+spec:
+  version: {{imageTag}}
+  ipFamily: IPv4
+  network:
+    ipFamilyPolicy: PreferDualStack
+    ipFamilies: ["IPv4", "IPv6"]  # IPv4 first, then IPv6
+  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:
+
+```yaml
+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 an IP family, ScyllaCluster will pick one automatically:**
+
+- **IPv4-only clusters**: Uses IPv4 (works like before)
+- **IPv6-only clusters**: Uses IPv6 automatically 
+- **Dual-stack clusters**: Uses the **first IP family** from your `network.ipFamilies` list
+- **No configuration**: Defaults to IPv4 for compatibility
+
+This means existing clusters keep working without any changes.
+::::
+
+### Configuration Options
+
+| Field | What it does | Default | Required? |
+|-------|-------------|---------|-----------|
+| `ipFamily` | IP version for ScyllaDB communication | Auto-detected or IPv4 | **Recommended** |
+| `network.ipFamilyPolicy` | How services handle IP versions | `SingleStack` | Only for advanced dual-stack |
+| `network.ipFamilies` | Which IP versions to support for services | `["IPv4"]` | Only for advanced dual-stack |
+
+::::{note}
+**When do you need `network` configuration?**
+
+- **Most cases**: Just set `ipFamily`, Kubernetes will auto-detect service networking
+- **Advanced dual-stack**: Use `network` fields only if you need explicit control over service IP families
+- **IPv4-only or IPv6-only clusters**: Just `ipFamily` is sufficient, no `network` config needed
+::::
+
+For detailed IPv6 configuration, troubleshooting, and examples, see the [IPv6 Networking Guide](./ipv6-networking.md).
+
 ## 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](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#pod-disruption-budgets) and keeping the cluster available.

diff --git a/docs/source/resources/scyllaclusters/index.md b/docs/source/resources/scyllaclusters/index.md
@@ -4,6 +4,7 @@
 :maxdepth: 1
 
 basics
+ipv6-networking
 clients/index
 nodeoperations/index
 multidc/index