kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #33997 from tengqm/reformat-dualstack 

Reformat dual-stack page
This commit is contained in:
Kubernetes Prow Robot 2022-06-06 18:35:50 -07:00 committed by GitHub
parent 49df29c4d0 41b519ee54
commit 09b7898081
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 179 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

306
content/en/docs/concepts/services-networking/dual-stack.md
View File

@ -1,16 +1,15 @@
--- ---
reviewers:
- lachie83
- khenidak
- aramase
- bridgetkromhout
title: IPv4/IPv6 dual-stack title: IPv4/IPv6 dual-stack
feature: feature:
title: IPv4/IPv6 dual-stack title: IPv4/IPv6 dual-stack
description: > description: >
Allocation of IPv4 and IPv6 addresses to Pods and Services Allocation of IPv4 and IPv6 addresses to Pods and Services
content_type: concept content_type: concept
reviewers:
- lachie83
- khenidak
- aramase
- bridgetkromhout
weight: 70 weight: 70
--- ---
@ -18,11 +17,11 @@ weight: 70
{{< feature-state for_k8s_version="v1.23" state="stable" >}} {{< feature-state for_k8s_version="v1.23" state="stable" >}}
IPv4/IPv6 dual-stack networking enables the allocation of both IPv4 and IPv6 addresses to {{< glossary_tooltip text="Pods" term_id="pod" >}} and {{< glossary_tooltip text="Services" term_id="service" >}}. IPv4/IPv6 dual-stack networking enables the allocation of both IPv4 and IPv6 addresses to
{{< glossary_tooltip text="Pods" term_id="pod" >}} and {{< glossary_tooltip text="Services" term_id="service" >}}.
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 networking is enabled by default for your Kubernetes cluster starting in
1.21, allowing the simultaneous assignment of both IPv4 and IPv6 addresses.
<!-- body --> <!-- body -->
@ -30,68 +29,78 @@ IPv4/IPv6 dual-stack networking is enabled by default for your Kubernetes cluste
IPv4/IPv6 dual-stack on your Kubernetes cluster provides the following features: IPv4/IPv6 dual-stack on your Kubernetes cluster provides the following features:
* Dual-stack Pod networking (a single IPv4 and IPv6 address assignment per Pod) * Dual-stack Pod networking (a single IPv4 and IPv6 address assignment per Pod)
* IPv4 and IPv6 enabled Services * IPv4 and IPv6 enabled Services
* Pod off-cluster egress routing (eg. the Internet) via both IPv4 and IPv6 interfaces * Pod off-cluster egress routing (eg. the Internet) via both IPv4 and IPv6 interfaces
## Prerequisites ## Prerequisites
The following prerequisites are needed in order to utilize IPv4/IPv6 dual-stack Kubernetes clusters: The following prerequisites are needed in order to utilize IPv4/IPv6 dual-stack Kubernetes clusters:
* Kubernetes 1.20 or later * Kubernetes 1.20 or later
For information about using dual-stack services with earlier
Kubernetes versions, refer to the documentation for that version For information about using dual-stack services with earlier
of Kubernetes. Kubernetes versions, refer to the documentation for that version
* Provider support for dual-stack networking (Cloud provider or otherwise must be able to provide Kubernetes nodes with routable IPv4/IPv6 network interfaces) of Kubernetes.
* A [network plugin](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) that supports dual-stack networking.
* Provider support for dual-stack networking (Cloud provider or otherwise must be able to provide
Kubernetes nodes with routable IPv4/IPv6 network interfaces)
* A [network plugin](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) that
supports dual-stack networking.
## Configure IPv4/IPv6 dual-stack ## Configure IPv4/IPv6 dual-stack
To configure IPv4/IPv6 dual-stack, set dual-stack cluster network assignments: To configure IPv4/IPv6 dual-stack, set dual-stack cluster network assignments:
* kube-apiserver: * kube-apiserver:
* `--service-cluster-ip-range=<IPv4 CIDR>,<IPv6 CIDR>` * `--service-cluster-ip-range=<IPv4 CIDR>,<IPv6 CIDR>`
* kube-controller-manager: * kube-controller-manager:
* `--cluster-cidr=<IPv4 CIDR>,<IPv6 CIDR>` * `--cluster-cidr=<IPv4 CIDR>,<IPv6 CIDR>`
* `--service-cluster-ip-range=<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 * `--node-cidr-mask-size-ipv4|--node-cidr-mask-size-ipv6` defaults to /24 for IPv4 and /64 for IPv6
* kube-proxy: * kube-proxy:
* `--cluster-cidr=<IPv4 CIDR>,<IPv6 CIDR>` * `--cluster-cidr=<IPv4 CIDR>,<IPv6 CIDR>`
* kubelet: * kubelet:
* when there is no `--cloud-provider` the administrator can pass a comma-separated pair * when there is no `--cloud-provider` the administrator can pass a comma-separated pair of IP
of IP addresses via `--node-ip` to manually configure dual-stack `.status.addresses` addresses via `--node-ip` to manually configure dual-stack `.status.addresses` for that Node.
for that Node. If a Pod runs on that node in HostNetwork mode, the Pod reports these IP addresses in its
If a Pod runs on that node in HostNetwork mode, the Pod reports these IP addresses in its `.status.podIPs` field.
`.status.podIPs` field. All `podIPs` in a node match the IP family preference defined by the `.status.addresses`
All `podIPs` in a node match the IP family preference defined by the field for that Node.
`.status.addresses` field for that Node.
{{< note >}} {{< note >}}
An example of an IPv4 CIDR: `10.244.0.0/16` (though you would supply your own address range) 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](https://tools.ietf.org/html/rfc4193)) An example of an IPv6 CIDR: `fdXY:IJKL:MNOP:15::/64` (this shows the format but is not a valid
address - see [RFC 4193](https://tools.ietf.org/html/rfc4193))
{{< /note >}} {{< /note >}}
## Services ## Services
You can create {{< glossary_tooltip text="Services" term_id="service" >}} which can use IPv4, IPv6, or both. You can create {{< glossary_tooltip text="Services" term_id="service" >}} 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). 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 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: 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. * `SingleStack`: Single-stack service. The control plane allocates a cluster IP for the Service,
using the first configured service cluster IP range.
* `PreferDualStack`: * `PreferDualStack`:
* Allocates IPv4 and IPv6 cluster IPs for the Service. * Allocates IPv4 and IPv6 cluster IPs for the Service.
* `RequireDualStack`: Allocates Service `.spec.ClusterIPs` from both IPv4 and IPv6 address ranges. * `RequireDualStack`: Allocates Service `.spec.ClusterIPs` from both IPv4 and IPv6 address ranges.
* Selects the `.spec.ClusterIP` from the list of `.spec.ClusterIPs` based on the address family of the first element in the `.spec.ipFamilies` array. * Selects the `.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. 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.
{{< note >}} {{< note >}}
The `.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. The `.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.
{{< /note >}} {{< /note >}}
You can set `.spec.ipFamilies` to any of the following array values: You can set `.spec.ipFamilies` to any of the following array values:
@ -109,131 +118,175 @@ These examples demonstrate the behavior of various dual-stack Service configurat
#### Dual-stack options on new Services #### 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.) 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.)
{{< codenew file="service/networking/dual-stack-default-svc.yaml" >}} {{< codenew file="service/networking/dual-stack-default-svc.yaml" >}}
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`. 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. * For the `.spec.ClusterIP` field, the control plane records the IP address that is from the
* On a single-stack cluster, the `.spec.ClusterIPs` and `.spec.ClusterIP` fields both only list one address. same address family as the first service cluster IP range.
* On a cluster with dual-stack enabled, specifying `RequireDualStack` in `.spec.ipFamilyPolicy` behaves the same as `PreferDualStack`. * 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`.
{{< codenew file="service/networking/dual-stack-preferred-svc.yaml" >}} {{< codenew file="service/networking/dual-stack-preferred-svc.yaml" >}}
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. 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.
{{< codenew file="service/networking/dual-stack-preferred-ipfamilies-svc.yaml" >}} {{< codenew file="service/networking/dual-stack-preferred-ipfamilies-svc.yaml" >}}
#### Dual-stack defaults on existing Services #### 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.) 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`. 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`.
{{< codenew file="service/networking/dual-stack-default-svc.yaml" >}} {{< codenew file="service/networking/dual-stack-default-svc.yaml" >}}
You can validate this behavior by using kubectl to inspect an existing service. You can validate this behavior by using kubectl to inspect an existing service.
```shell ```shell
kubectl get svc my-service -o yaml kubectl get svc my-service -o yaml
``` ```
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Service kind: Service
metadata: metadata:
labels: labels:
app: MyApp app: MyApp
name: my-service name: my-service
spec: spec:
clusterIP: 10.0.197.123 clusterIP: 10.0.197.123
clusterIPs: clusterIPs:
- 10.0.197.123 - 10.0.197.123
ipFamilies: ipFamilies:
- IPv4 - IPv4
ipFamilyPolicy: SingleStack ipFamilyPolicy: SingleStack
ports: ports:
- port: 80 - port: 80
protocol: TCP protocol: TCP
targetPort: 80 targetPort: 80
selector: selector:
app: MyApp app: MyApp
type: ClusterIP type: ClusterIP
status: status:
loadBalancer: {} 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`. 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`.
{{< codenew file="service/networking/dual-stack-default-svc.yaml" >}} {{< codenew file="service/networking/dual-stack-default-svc.yaml" >}}
You can validate this behavior by using kubectl to inspect an existing headless service with selectors. You can validate this behavior by using kubectl to inspect an existing headless service with selectors.
```shell ```shell
kubectl get svc my-service -o yaml kubectl get svc my-service -o yaml
``` ```
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Service kind: Service
metadata: metadata:
labels: labels:
app: MyApp app: MyApp
name: my-service name: my-service
spec: spec:
clusterIP: None clusterIP: None
clusterIPs: clusterIPs:
- None - None
ipFamilies: ipFamilies:
- IPv4 - IPv4
ipFamilyPolicy: SingleStack ipFamilyPolicy: SingleStack
ports: ports:
- port: 80 - port: 80
protocol: TCP protocol: TCP
targetPort: 80 targetPort: 80
selector: selector:
app: MyApp app: MyApp
``` ```
#### Switching Services between single-stack and dual-stack #### 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. 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. 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`. Edit the Service specification updating the `.spec.ipFamilyPolicy` from `SingleStack` to `PreferDualStack`.
Before: 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`. ```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 ### 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`. 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 ### Service type LoadBalancer
To provision a dual-stack load balancer for your Service: 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` * Set the `.spec.type` field to `LoadBalancer`
* Set `.spec.ipFamilyPolicy` field to `PreferDualStack` or `RequireDualStack`
{{< note >}} {{< note >}}
To use a dual-stack `LoadBalancer` type Service, your cloud provider must support IPv4 and IPv6 load balancers. To use a dual-stack `LoadBalancer` type Service, your cloud provider must support IPv4 and IPv6
load balancers.
{{< /note >}} {{< /note >}}
## Egress traffic ## 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. 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 >}} {{< note >}}
Ensure your {{< glossary_tooltip text="CNI" term_id="cni" >}} provider supports IPv6. Ensure your {{< glossary_tooltip text="CNI" term_id="cni" >}} provider supports IPv6.
@ -256,7 +309,6 @@ You can read more about the different network modes for Windows within the
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
* [Validate IPv4/IPv6 dual-stack](/docs/tasks/network/validate-dual-stack) networking * [Validate IPv4/IPv6 dual-stack](/docs/tasks/network/validate-dual-stack) networking
* [Enable dual-stack networking using kubeadm * [Enable dual-stack networking using kubeadm](/docs/setup/production-environment/tools/kubeadm/dual-stack-support/)
](/docs/setup/production-environment/tools/kubeadm/dual-stack-support/)