whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reformat dual-stack page

Browse Source 
Reformat the page for wrapping long lines and indenting lists properly.
This commit is contained in:
Qiming Teng
2022-05-28 11:18:53 +08:00
parent bcc5507d79
commit 41b519ee54
1 changed files with 179 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/services-networking/dual-stack.md
+93 -41
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 -->
@@ -39,11 +38,15 @@ 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: 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 For information about using dual-stack services with earlier
Kubernetes versions, refer to the documentation for that version Kubernetes versions, refer to the documentation for that version
of Kubernetes. of Kubernetes.
* 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. * 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
@@ -58,40 +61,46 @@ To configure IPv4/IPv6 dual-stack, set dual-stack cluster network assignments:
* 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 All `podIPs` in a node match the IP family preference defined by the `.status.addresses`
`.status.addresses` field for that Node. 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,27 +118,48 @@ 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" >}}
@@ -164,7 +194,12 @@ 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" >}}
@@ -200,40 +235,58 @@ spec:
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 ```yaml
spec: spec:
ipFamilyPolicy: SingleStack ipFamilyPolicy: SingleStack
``` ```
After: After:
```yaml ```yaml
spec: spec:
ipFamilyPolicy: PreferDualStack 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`. 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 the `.spec.type` field to `LoadBalancer`
* Set `.spec.ipFamilyPolicy` field to `PreferDualStack` or `RequireDualStack` * 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/)