Document dual-stack requirement for IPv6 backends

Author: komer3

docs/configuration/annotations.md

@@ -40,7 +40,7 @@ The keys and the values in [annotations must be strings](https://kubernetes.io/d
 | `firewall-acl` | string | | The Firewall rules to be applied to the NodeBalancer. See [Firewall Configuration](#firewall-configuration) |
 | `nodebalancer-type` | string | | The type of NodeBalancer to create (options: common, premium, premium_40gb). See [NodeBalancer Types](#nodebalancer-type). Note: NodeBalancer types should always be specified in lowercase. |
 | `enable-ipv6-ingress` | bool | `false` | When `true`, both IPv4 and IPv6 addresses will be included in the LoadBalancerStatus ingress |
-| `enable-ipv6-backends` | bool | `false` | When `true`, non-VPC NodeBalancer services use public IPv6 backend nodes, and reconciliation fails if a selected backend node does not have public IPv6. |
+| `enable-ipv6-backends` | bool | `false` | When `true`, non-VPC NodeBalancer services use public IPv6 backend nodes. This requires a dual-stack cluster and a dual-stack Service configuration. Reconciliation fails if a selected backend node does not have public IPv6. |
 | `backend-ipv4-range` | string | | The IPv4 range from VPC subnet to be applied to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `backend-vpc-name` | string | | VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `backend-subnet-name` | string | | Subnet within VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |

docs/configuration/environment.md

@@ -53,7 +53,7 @@ The CCM supports the following flags:
 | `--nodebalancer-backend-ipv4-subnet-name` | String | `""` | ipv4 subnet name to use for NodeBalancer backends |
 | `--disable-nodebalancer-vpc-backends` | Boolean | `false` | don't use VPC specific ip-addresses for nodebalancer backend ips when running in VPC (set to `true` for backward compatibility if needed) |
 | `--enable-ipv6-for-loadbalancers` | Boolean | `false` | Set both IPv4 and IPv6 addresses for all LoadBalancer services (when disabled, only IPv4 is used). This can also be configured per-service using the `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-ingress` annotation. |
-| `--enable-ipv6-for-nodebalancer-backends` | Boolean | `false` | Use public IPv6 addresses for non-VPC NodeBalancer service backends. If enabled, every selected backend node must have public IPv6 or reconciliation will fail. This can also be configured per-service using the `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends` annotation. |
+| `--enable-ipv6-for-nodebalancer-backends` | Boolean | `false` | Use public IPv6 addresses for non-VPC NodeBalancer service backends. This requires a dual-stack cluster and dual-stack Service configuration. If enabled, every selected backend node must have public IPv6 or reconciliation will fail. This can also be configured per-service using the `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends` annotation. |
 | `--node-cidr-mask-size-ipv4` | Int | `24` | ipv4 cidr mask size for pod cidrs allocated to nodes |
 | `--node-cidr-mask-size-ipv6` | Int | `64` | ipv6 cidr mask size for pod cidrs allocated to nodes |
 | `--nodebalancer-prefix` | String | `ccm` | Name prefix for NoadBalancers. |

docs/configuration/loadbalancer.md

@@ -48,6 +48,8 @@ When IPv6 is enabled (either globally or per-service), both IPv4 and IPv6 addres
 
 IPv6 frontends and IPv6 backends are configured independently. Frontend IPv6 controls what the Service publishes in `status.loadBalancer.ingress`, while backend IPv6 controls which node addresses a NodeBalancer targets.
 
+IPv6 backends require a dual-stack workload cluster. In practice, the cluster networking stack must support IPv6 NodePort traffic, and the Service itself should be created as dual-stack. A single-stack IPv4 `LoadBalancer` Service can still be annotated for IPv6 backends, but the NodeBalancer health checks and traffic path may fail because the backend NodePort is not exposed over IPv6.
+
 For newly created non-VPC NodeBalancer services, you can enable public IPv6 backends globally:
 
 ```yaml
@@ -72,10 +74,35 @@ When IPv6 backends are enabled:
 - only non-VPC NodeBalancer services are affected
 - existing services are not migrated automatically
 - every selected backend node must have public IPv6
+- the workload cluster and Service must be configured for dual-stack networking
 - reconciliation fails and CCM logs an error if a selected backend node does not have public IPv6
 
 VPC backend behavior is unchanged and continues to use the existing IPv4/VPC backend flow.
 
+Recommended Service configuration for IPv6 backends:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends: "true"
+spec:
+  type: LoadBalancer
+  ipFamilyPolicy: RequireDualStack
+  ipFamilies:
+    - IPv4
+    - IPv6
+  ports:
+    - port: 80
+      targetPort: 8080
+  selector:
+    app: my-app
+```
+
+If your cluster does not provide IPv6-capable NodePort routing, the NodeBalancer may still be created with IPv6 backend addresses, but the backends will not become healthy.
+
 ### Basic Configuration
 
 Create a LoadBalancer service: