Pod Hostname
This page explains how to set a Pod's hostname, potential side effects after configuration, and the underlying mechanics.
Default Pod Hostname
When a Pod is created, its hostname (as observed from within the Pod) is derived from the Pod's metadata.name value. Both the hostname and its corresponding fully qualified domain name (FQDN) are set to the metadata.name value (from the Pod's perspective)
apiVersion: v1
kind: Pod
metadata:
name: busybox-1
spec:
containers:
- image: busybox:1.28
command:
- sleep
- "3600"
name: busybox
The Pod created by this manifest will have its hostname and fully qualified domain name (FQDN) set to busybox-1
.
Hostname with pod's hostname and subdomain fields
The Pod spec includes an optional hostname
field.
When set, this value takes precedence over the Pod's metadata.name
as the
hostname (observed from within the Pod).
For example, a Pod with spec.hostname set to my-host
will have its hostname set to my-host
.
The Pod spec also includes an optional subdomain
field,
indicating the Pod belongs to a subdomain within its namespace.
If a Pod has spec.hostname
set to "foo" and spec.subdomain set
to "bar" in the namespace my-namespace
, its hostname becomes foo
and its
fully qualified domain name (FQDN) becomes
foo.bar.my-namespace.svc.cluster-domain.example
(observed from within the Pod).
When both hostname and subdomain are set, the cluster's DNS server will create A and/or AAAA records based on these fields. Refer to: Pod's hostname and subdomain fields.
Hostname with pod's setHostnameAsFQDN fields
Kubernetes v1.22 [stable]
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.busybox-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 both setHostnameAsFQDN: true
and the subdomain field is set 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.
The Pod's FQDN is constructed in the same manner as previously defined.
It is composed of the Pod's spec.hostname
(if specified) or metadata.name
field,
the spec.subdomain
, the namespace
name, and the cluster domain suffix.
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".
This means that when using this field,
you must ensure the combined length of the Pod's metadata.name
(or spec.hostname
)
and spec.subdomain
fields results in an FQDN that does not exceed 64 characters.
Hostname with pod's hostnameOverride
Kubernetes v1.34 [alpha]
(enabled by default: false)Setting a value for hostnameOverride
in the Pod spec causes the kubelet
to unconditionally set both the Pod's hostname and fully qualified domain name (FQDN)
to the hostnameOverride
value.
The hostnameOverride field has a length limitation of 64 characters and must adhere to the DNS subdomain names standard defined in RFC 1123.
Example:
apiVersion: v1
kind: Pod
metadata:
name: busybox-2-busybox-example-domain
spec:
hostnameOverride: busybox-2.busybox.example.domain
containers:
- image: busybox:1.28
command:
- sleep
- "3600"
name: busybox
Note:
This only affects the hostname within the Pod; it does not affect the Pod's A or AAAA records in the cluster DNS server.If hostnameOverride is set alongside hostname and subdomain fields:
- The hostname inside the Pod is overridden to the hostnameOverride value.
- The Pod's A and/or AAAA records in the cluster DNS server are still generated based on the hostname and subdomain fields.
Note: If hostnameOverride
is set, you cannot simultaneously set the hostNetwork
and setHostnameAsFQDN
fields.
The API server will explicitly reject any create request attempting this combination.
For details on behavior when hostnameOverride
is set in combination with
other fields (hostname, subdomain, setHostnameAsFQDN, hostNetwork),
see the table in the KEP-4762 design details.