Kubernetes v1.23 [stable]
IPv4/IPv6 dual-stack networking enables the allocation of both IPv4 and IPv6 addresses to Pods and Services.
IPv4/IPv6 dual-stack networking is enabled by default for your Kubernetes cluster starting in 1.21, allowing the simultaneous assignment of both IPv4 and IPv6 addresses.
IPv4/IPv6 dual-stack on your Kubernetes cluster provides the following features:
The following prerequisites are needed in order to utilize IPv4/IPv6 dual-stack Kubernetes clusters:
To configure IPv4/IPv6 dual-stack, set dual-stack cluster network assignments:
--service-cluster-ip-range=<IPv4 CIDR>,<IPv6 CIDR>
--cluster-cidr=<IPv4 CIDR>,<IPv6 CIDR>
--service-cluster-ip-range=<IPv4 CIDR>,<IPv6 CIDR>
--node-cidr-mask-size-ipv4|--node-cidr-mask-size-ipv6
defaults to /24 for IPv4 and /64 for IPv6--cluster-cidr=<IPv4 CIDR>,<IPv6 CIDR>
--cloud-provider
the administrator can pass a comma-separated pair of IP addresses via --node-ip
to manually configure dual-stack .status.addresses
for that Node. If a Pod runs on that node in HostNetwork mode, the Pod reports these IP addresses in its .status.podIPs
field. All podIPs
in a node match the IP family preference defined by the .status.addresses
field for that Node.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)
You can create Services which can use IPv4, IPv6, or both.
The address family of a Service defaults to the address family of the first service cluster IP range (configured via the --service-cluster-ip-range
flag to the kube-apiserver).
When you define a Service you can optionally configure it as dual stack. To specify the behavior you want, you set the .spec.ipFamilyPolicy
field to one of the following values:
SingleStack
: Single-stack service. The control plane allocates a cluster IP for the Service, using the first configured service cluster IP range.PreferDualStack
: RequireDualStack
: Allocates Service .spec.ClusterIPs
from both IPv4 and IPv6 address ranges. .spec.ClusterIP
from the list of .spec.ClusterIPs
based on the address family of the first element in the .spec.ipFamilies
array.If you would like to define which IP family to use for single stack or define the order of IP families for dual-stack, you can choose the address families by setting an optional field, .spec.ipFamilies
, on the Service.
.spec.ipFamilies
field is immutable because the .spec.ClusterIP
cannot be reallocated on a Service that already exists. If you want to change .spec.ipFamilies
, delete and recreate the 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.
These examples demonstrate the behavior of various dual-stack Service configuration scenarios.
.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 and headless Services with selectors will behave in this same way.)service/networking/dual-stack-default-svc.yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app: MyApp
spec:
selector:
app: MyApp
ports:
- protocol: TCP
port: 80
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
.
.spec.ClusterIP
field, the control plane records the IP address that is from the same address family as the first service cluster IP range..spec.ClusterIPs
and .spec.ClusterIP
fields both only list one address.RequireDualStack
in .spec.ipFamilyPolicy
behaves the same as PreferDualStack
.service/networking/dual-stack-preferred-svc.yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app: MyApp
spec:
ipFamilyPolicy: PreferDualStack
selector:
app: MyApp
ports:
- protocol: TCP
port: 80
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.service/networking/dual-stack-preferred-ipfamilies-svc.yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app: MyApp
spec:
ipFamilyPolicy: PreferDualStack
ipFamilies:
- IPv6
- IPv4
selector:
app: MyApp
ports:
- protocol: TCP
port: 80
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.)
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
.service/networking/dual-stack-default-svc.yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app: MyApp
spec:
selector:
app: MyApp
ports:
- protocol: TCP
port: 80
You can validate this behavior by using kubectl to inspect an existing service.
kubectl get svc my-service -o yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: 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: MyApp
type: ClusterIP
status:
loadBalancer: {}
.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
.service/networking/dual-stack-default-svc.yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app: MyApp
spec:
selector:
app: MyApp
ports:
- protocol: TCP
port: 80
You can validate this behavior by using kubectl to inspect an existing headless service with selectors.
kubectl get svc my-service -o yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: MyApp
name: my-service
spec:
clusterIP: None
clusterIPs:
- None
ipFamilies:
- IPv4
ipFamilyPolicy: SingleStack
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: MyApp
Services can be changed from single-stack to dual-stack and from dual-stack to single-stack.
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:
spec:
ipFamilyPolicy: SingleStack
After:
spec:
ipFamilyPolicy: PreferDualStack
.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
.For Headless Services without selectors and without .spec.ipFamilyPolicy
explicitly set, the .spec.ipFamilyPolicy
field defaults to RequireDualStack
.
To provision a dual-stack load balancer for your Service:
.spec.type
field to LoadBalancer
.spec.ipFamilyPolicy
field to PreferDualStack
or RequireDualStack
LoadBalancer
type Service, your cloud provider must support IPv4 and IPv6 load balancers. 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 project supports IP masquerading on dual-stack clusters.
© 2022 The Kubernetes Authors
Documentation Distributed under CC BY 4.0.
https://kubernetes.io/docs/concepts/services-networking/dual-stack/