Adding entries to Pod /etc/hosts with HostAliases

Adding entries to a Pod’s /etc/hosts file provides Pod-level override of hostname resolution when DNS and other options are not applicable. You can add these custom entries with the HostAliases field in PodSpec.

Modification not using HostAliases is not suggested because the file is managed by the kubelet and can be overwritten on during Pod creation/restart.

Default hosts file content

Start an Nginx Pod which is assigned a Pod IP:

  1. kubectl run nginx --image nginx
  1. pod/nginx created

Examine a Pod IP:

  1. kubectl get pods --output=wide
  1. NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
  2. nginx    1/1       Running   0          13s    10.200.0.4   worker0

The hosts file content would look like this:

  1. kubectl exec nginx -- cat /etc/hosts
  1. # Kubernetes-managed hosts file.
  2. 127.0.0.1    localhost
  3. ::1    localhost ip6-localhost ip6-loopback
  4. fe00::0    ip6-localnet
  5. fe00::0    ip6-mcastprefix
  6. fe00::1    ip6-allnodes
  7. fe00::2    ip6-allrouters
  8. 10.200.0.4    nginx

By default, the hosts file only includes IPv4 and IPv6 boilerplates like localhost and its own hostname.

Adding additional entries with hostAliases

In addition to the default boilerplate, you can add additional entries to the hosts file. For example: to resolve foo.local, bar.local to 127.0.0.1 and foo.remote, bar.remote to 10.1.2.3, you can configure HostAliases for a Pod under .spec.hostAliases:

service/networking/hostaliases-pod.yaml Adding entries to Pod /etc/hosts with HostAliases - 图1

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4.   name: hostaliases-pod
  5. spec:
  6.   restartPolicy: Never
  7.   hostAliases:
  8.   - ip: "127.0.0.1"
  9.     hostnames:
  10.     - "foo.local"
  11.     - "bar.local"
  12.   - ip: "10.1.2.3"
  13.     hostnames:
  14.     - "foo.remote"
  15.     - "bar.remote"
  16.   containers:
  17.   - name: cat-hosts
  18.     image: busybox:1.28
  19.     command:
  20.     - cat
  21.     args:
  22.     - "/etc/hosts"

You can start a Pod with that configuration by running:

  1. kubectl apply -f https://k8s.io/examples/service/networking/hostaliases-pod.yaml
  1. pod/hostaliases-pod created

Examine a Pod’s details to see its IPv4 address and its status:

  1. kubectl get pod --output=wide
  1. NAME                           READY     STATUS      RESTARTS   AGE       IP              NODE
  2. hostaliases-pod                0/1       Completed   0          6s        10.200.0.5      worker0

The hosts file content looks like this:

  1. kubectl logs hostaliases-pod
  1. # Kubernetes-managed hosts file.
  2. 127.0.0.1    localhost
  3. ::1    localhost ip6-localhost ip6-loopback
  4. fe00::0    ip6-localnet
  5. fe00::0    ip6-mcastprefix
  6. fe00::1    ip6-allnodes
  7. fe00::2    ip6-allrouters
  8. 10.200.0.5    hostaliases-pod
  10. # Entries added by HostAliases.
  11. 127.0.0.1    foo.local    bar.local
  12. 10.1.2.3    foo.remote    bar.remote

with the additional entries specified at the bottom.

Why does the kubelet manage the hosts file?

The kubelet manages the hosts file for each container of the Pod to prevent the container runtime from modifying the file after the containers have already been started. Historically, Kubernetes always used Docker Engine as its container runtime, and Docker Engine would then modify the /etc/hosts file after each container had started.

Current Kubernetes can use a variety of container runtimes; even so, the kubelet manages the hosts file within each container so that the outcome is as intended regardless of which container runtime you use.

Caution:

Avoid making manual changes to the hosts file inside a container.

If you make manual changes to the hosts file, those changes are lost when the container exits.