From 64422b159ab6a48e8dd169345b7d891d7937048c Mon Sep 17 00:00:00 2001 From: Javier Diaz-Montes Date: Fri, 19 Jun 2020 10:05:55 -0400 Subject: [PATCH] Documenting setHostnameAsFQDN feature KEP: kubernetes/enhancements#1797 and kubernetes/enhancements#1792 Code PR: kubernetes/kubernetes#91699 --- .../concepts/services-networking/dns-pod-service.md | 12 ++++++++++++ .../command-line-tools-reference/feature-gates.md | 2 ++ 2 files changed, 14 insertions(+) diff --git a/content/en/docs/concepts/services-networking/dns-pod-service.md b/content/en/docs/concepts/services-networking/dns-pod-service.md index 9d88019e3c..9938062af3 100644 --- a/content/en/docs/concepts/services-networking/dns-pod-service.md +++ b/content/en/docs/concepts/services-networking/dns-pod-service.md @@ -157,6 +157,18 @@ pointing to the Pod's IP address. Also, Pod needs to become ready in order to ha record unless `publishNotReadyAddresses=True` is set on the Service. {{< /note >}} +### Pod's setHostnameAsFQDN field {#pod-sethostnameasfqdn-field} + +When a Pod is configured to have fully qualified domain name (FQDN), its hostname is the short hostname. For example, if you have a Pod with the fully qualified domain name `busybox-1.default-subdomain.my-namespace.svc.cluster-domain.example`, then by default the `hostname` command inside that Pod returns `busybox-1` and the `hostname --fqdn` command returns the FQDN. + +When you set `setHostnameAsFQDN: true` in the Pod spec, the kubelet writes the Pod's FQDN into the hostname for that Pod's namespace. In this case, both `hostname` and `hostname --fqdn` return the Pod's FQDN. + +{{< note >}} +In Linux, the hostname field of the kernel (the `nodename` field of `struct utsname`) is limited to 64 characters. + +If a Pod enables this feature and its FQDN is longer than 64 character, it will fail to start. The Pod will remain in `Pending` status (`ContainerCreating` as seen by `kubectl`) generating error events, such as Failed to construct FQDN from pod hostname and cluster domain, FQDN `long-FDQN` is too long (64 characters is the max, 70 characters requested). One way of improving user experience for this scenario is to create an [admission webhook controller](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) to control FQDN size when users create top level objects, for example, Deployment. +{{< /note >}} + ### Pod's DNS Policy DNS policies can be set on a per-pod basis. Currently Kubernetes supports the diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index b956af4234..99610dace6 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -137,6 +137,7 @@ different Kubernetes components. | `ServerSideApply` | `true` | Beta | 1.16 | | | `ServiceNodeExclusion` | `false` | Alpha | 1.8 | | | `ServiceTopology` | `false` | Alpha | 1.17 | | +| `SetHostnameAsFQDN` | `false` | Alpha | 1.19 | | | `StartupProbe` | `false` | Alpha | 1.16 | 1.17 | | `StartupProbe` | `true` | Beta | 1.18 | | | `StorageVersionHash` | `false` | Alpha | 1.14 | 1.14 | @@ -484,6 +485,7 @@ Each feature gate is designed for enabling/disabling a specific feature: - `ServiceNodeExclusion`: Enable the exclusion of nodes from load balancers created by a cloud provider. A node is eligible for exclusion if labelled with "`alpha.service-controller.kubernetes.io/exclude-balancer`" key or `node.kubernetes.io/exclude-from-external-load-balancers`. - `ServiceTopology`: Enable service to route traffic based upon the Node topology of the cluster. See [ServiceTopology](https://kubernetes.io/docs/concepts/services-networking/service-topology/) for more details. +- `SetHostnameAsFQDN`: Enable the ability of setting Fully Qualified Domain Name(FQDN) as hostname of pod. See [Pod's `setHostnameAsFQDN` field](/docs/concepts/services-networking/dns-pod-service/#pod-sethostnameasfqdn-field). - `StartupProbe`: Enable the [startup](/docs/concepts/workloads/pods/pod-lifecycle/#when-should-you-use-a-startup-probe) probe in the kubelet. - `StorageObjectInUseProtection`: Postpone the deletion of PersistentVolume or PersistentVolumeClaim objects if they are still being used.