`
* This option is required for bare metal dual-stack nodes (nodes that do not define a
cloud provider with the `--cloud-provider` flag). If you are using a cloud provider
and choose to override the node IPs chosen by the cloud provider, set the
`--node-ip` option.
* (The legacy built-in cloud providers do not support dual-stack `--node-ip`.)
Note:
An example of an IPv4 CIDR: 10.244.0.0/16 (though you would supply your own address range)
An example of an IPv6 CIDR: fdXY:IJKL:MNOP:15::/64 (this shows the format but is not a valid
address - see RFC 4193)
Note:
The .spec.ipFamilies field is conditionally mutable: you can add or remove a secondary
IP address family, but you cannot change the primary IP address family of an existing Service.
You can set `.spec.ipFamilies` to any of the following array values:
- `["IPv4"]`
- `["IPv6"]`
- `["IPv4","IPv6"]` (dual stack)
- `["IPv6","IPv4"]` (dual stack)
The first family you list is used for the legacy `.spec.clusterIP` field.
### Dual-stack Service configuration scenarios
These examples demonstrate the behavior of various dual-stack Service configuration scenarios.
#### Dual-stack options on new Services
1. This Service specification does not explicitly define `.spec.ipFamilyPolicy`. When you create
this Service, Kubernetes assigns a cluster IP for the Service from the first configured
`service-cluster-ip-range` and sets the `.spec.ipFamilyPolicy` to `SingleStack`. ([Services
without selectors](/docs/concepts/services-networking/service/#services-without-selectors) and
[headless Services](/docs/concepts/services-networking/service/#headless-services) with selectors
will behave in this same way.)
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app.kubernetes.io/name: MyApp
spec:
selector:
app.kubernetes.io/name: MyApp
ports:
- protocol: TCP
port: 80
1. This Service specification explicitly defines `PreferDualStack` in `.spec.ipFamilyPolicy`. When
you create this Service on a dual-stack cluster, Kubernetes assigns both IPv4 and IPv6
addresses for the service. The control plane updates the `.spec` for the Service to record the IP
address assignments. The field `.spec.clusterIPs` is the primary field, and contains both assigned
IP addresses; `.spec.clusterIP` is a secondary field with its value calculated from
`.spec.clusterIPs`.
* For the `.spec.clusterIP` field, the control plane records the IP address that is from the
same address family as the first service cluster IP range.
* On a single-stack cluster, the `.spec.clusterIPs` and `.spec.clusterIP` fields both only list
one address.
* On a cluster with dual-stack enabled, specifying `RequireDualStack` in `.spec.ipFamilyPolicy`
behaves the same as `PreferDualStack`.
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app.kubernetes.io/name: MyApp
spec:
ipFamilyPolicy: PreferDualStack
selector:
app.kubernetes.io/name: MyApp
ports:
- protocol: TCP
port: 80
1. This Service specification explicitly defines `IPv6` and `IPv4` in `.spec.ipFamilies` as well
as defining `PreferDualStack` in `.spec.ipFamilyPolicy`. When Kubernetes assigns an IPv6 and
IPv4 address in `.spec.clusterIPs`, `.spec.clusterIP` is set to the IPv6 address because that is
the first element in the `.spec.clusterIPs` array, overriding the default.
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app.kubernetes.io/name: MyApp
spec:
ipFamilyPolicy: PreferDualStack
ipFamilies:
- IPv6
- IPv4
selector:
app.kubernetes.io/name: MyApp
ports:
- protocol: TCP
port: 80
#### Dual-stack defaults on existing Services
These examples demonstrate the default behavior when dual-stack is newly enabled on a cluster
where Services already exist. (Upgrading an existing cluster to 1.21 or beyond will enable
dual-stack.)
1. When dual-stack is enabled on a cluster, existing Services (whether `IPv4` or `IPv6`) are
configured by the control plane to set `.spec.ipFamilyPolicy` to `SingleStack` and set
`.spec.ipFamilies` to the address family of the existing Service. The existing Service cluster IP
will be stored in `.spec.clusterIPs`.
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app.kubernetes.io/name: MyApp
spec:
selector:
app.kubernetes.io/name: MyApp
ports:
- protocol: TCP
port: 80
You can validate this behavior by using kubectl to inspect an existing service.
```shell
kubectl get svc my-service -o yaml
```
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: MyApp
name: my-service
spec:
clusterIP: 10.0.197.123
clusterIPs:
- 10.0.197.123
ipFamilies:
- IPv4
ipFamilyPolicy: SingleStack
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app.kubernetes.io/name: MyApp
type: ClusterIP
status:
loadBalancer: {}
```
1. When dual-stack is enabled on a cluster, existing
[headless Services](/docs/concepts/services-networking/service/#headless-services) with selectors are
configured by the control plane to set `.spec.ipFamilyPolicy` to `SingleStack` and set
`.spec.ipFamilies` to the address family of the first service cluster IP range (configured via the
`--service-cluster-ip-range` flag to the kube-apiserver) even though `.spec.clusterIP` is set to
`None`.
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app.kubernetes.io/name: MyApp
spec:
selector:
app.kubernetes.io/name: MyApp
ports:
- protocol: TCP
port: 80
You can validate this behavior by using kubectl to inspect an existing headless service with selectors.
```shell
kubectl get svc my-service -o yaml
```
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: MyApp
name: my-service
spec:
clusterIP: None
clusterIPs:
- None
ipFamilies:
- IPv4
ipFamilyPolicy: SingleStack
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app.kubernetes.io/name: MyApp
```
#### Switching Services between single-stack and dual-stack
Services can be changed from single-stack to dual-stack and from dual-stack to single-stack.
1. To change a Service from single-stack to dual-stack, change `.spec.ipFamilyPolicy` from
`SingleStack` to `PreferDualStack` or `RequireDualStack` as desired. When you change this
Service from single-stack to dual-stack, Kubernetes assigns the missing address family so that the
Service now has IPv4 and IPv6 addresses.
Edit the Service specification updating the `.spec.ipFamilyPolicy` from `SingleStack` to `PreferDualStack`.
Before:
```yaml
spec:
ipFamilyPolicy: SingleStack
```
After:
```yaml
spec:
ipFamilyPolicy: PreferDualStack
```
1. To change a Service from dual-stack to single-stack, change `.spec.ipFamilyPolicy` from
`PreferDualStack` or `RequireDualStack` to `SingleStack`. When you change this Service from
dual-stack to single-stack, Kubernetes retains only the first element in the `.spec.clusterIPs`
array, and sets `.spec.clusterIP` to that IP address and sets `.spec.ipFamilies` to the address
family of `.spec.clusterIPs`.
### Headless Services without selector
For [Headless Services without selectors](/docs/concepts/services-networking/service/#without-selectors)
and without `.spec.ipFamilyPolicy` explicitly set, the `.spec.ipFamilyPolicy` field defaults to
`RequireDualStack`.
### Service type LoadBalancer
To provision a dual-stack load balancer for your Service:
* Set the `.spec.type` field to `LoadBalancer`
* Set `.spec.ipFamilyPolicy` field to `PreferDualStack` or `RequireDualStack`
Note:
To use a dual-stack LoadBalancer type Service, your cloud provider must support IPv4 and IPv6
load balancers.
## Egress traffic
If you want to enable egress traffic in order to reach off-cluster destinations (eg. the public
Internet) from a Pod that uses non-publicly routable IPv6 addresses, you need to enable the Pod to
use a publicly routed IPv6 address via a mechanism such as transparent proxying or IP
masquerading. The [ip-masq-agent](https://github.com/kubernetes-sigs/ip-masq-agent) project
supports IP masquerading on dual-stack clusters.
Note:
Ensure your
CNI provider supports IPv6.
Note:
Overlay (VXLAN) networks on Windows do not support dual-stack networking.
You can read more about the different network modes for Windows within the
[Networking on Windows](/docs/concepts/services-networking/windows-networking#network-modes) topic.
## What's next
* [Validate IPv4/IPv6 dual-stack](/docs/tasks/network/validate-dual-stack) networking
* [Enable dual-stack networking using kubeadm](/docs/setup/production-environment/tools/kubeadm/dual-stack-support/)
