From 79754a0ffacce301c7749a2871582d3dbb74546e Mon Sep 17 00:00:00 2001 From: Ricky Pai Date: Tue, 27 Jun 2017 09:19:41 -0700 Subject: [PATCH] documentation for using hostAliases to manage hosts file (#4080) * documentation for using hostAliases to manage hosts file * add to table of contents * review comments * update the right command to see hosts file * reformat doc based on suggestion and change some wording --- _data/concepts.yml | 1 + ...ries-to-pod-etc-hosts-with-host-aliases.md | 75 +++++++++++++++++++ .../services-networking/hostaliases-pod.yaml | 21 ++++++ 3 files changed, 97 insertions(+) create mode 100644 docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md create mode 100644 docs/concepts/services-networking/hostaliases-pod.yaml diff --git a/_data/concepts.yml b/_data/concepts.yml index 7e0a1172b4..f189bc60af 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -66,6 +66,7 @@ toc: - docs/concepts/services-networking/connect-applications-service.md - docs/concepts/services-networking/ingress.md - docs/concepts/services-networking/network-policies.md + - docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md - title: Storage section: diff --git a/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md b/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md new file mode 100644 index 0000000000..d0bb233218 --- /dev/null +++ b/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md @@ -0,0 +1,75 @@ +--- +assignees: +- rickypai +- thockin +title: Adding entries to Pod /etc/hosts with HostAliases +redirect_from: +- "/docs/user-guide/add-entries-to-pod-etc-hosts-with-host-aliases/" +- "/docs/user-guide/add-entries-to-pod-etc-hosts-with-host-aliases.md" +--- + +* TOC +{:toc} + +Adding entries to a Pod's /etc/hosts file provides Pod-level override of hostname resolution when DNS and other options are not applicable. In 1.7, users can add these custom entries with the HostAliases field in PodSpec. + +Modification not using HostAliases is not suggested because the file is managed by Kubetlet and can be overwritten on during Pod creation/restart. + +## Default Hosts File Content + +Lets start an Nginx Pod which is assigned an Pod IP: +``` +$ kubectl get pods --output=wide +NAME READY STATUS RESTARTS AGE IP NODE +nginx 1/1 Running 0 13s 10.200.0.4 worker0 +``` + +The hosts file content would look like this: +``` +$ kubectl exec nginx -- cat /etc/hosts +# Kubernetes-managed hosts file. +127.0.0.1 localhost +::1 localhost ip6-localhost ip6-loopback +fe00::0 ip6-localnet +fe00::0 ip6-mcastprefix +fe00::1 ip6-allnodes +fe00::2 ip6-allrouters +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 the the default boilerplate, we can add additional entries to the hosts file to resolve `foo.local`, `bar.local` to `127.0.0.1` and `foo.remote`, `bar.remote` to `10.1.2.3`, we can by adding HostAliases to the Pod under `.spec.hostAliases`: + +{% include code.html language="yaml" file="hostaliases-pod.yaml" ghlink="/docs/concepts/services-networking/hostaliases-pod.yaml" %} + +The hosts file content would look like this: +``` +$ kubectl logs hostaliases-pod +# Kubernetes-managed hosts file. +127.0.0.1 localhost +::1 localhost ip6-localhost ip6-loopback +fe00::0 ip6-localnet +fe00::0 ip6-mcastprefix +fe00::1 ip6-allnodes +fe00::2 ip6-allrouters +10.200.0.4 hostaliases-pod +127.0.0.1 foo.local +127.0.0.1 bar.local +10.1.2.3 foo.remote +10.1.2.3 bar.remote +``` + +With the additional entries specified at the bottom. + +## Limitations + +As of 1.7, Pods with hostNetwork enabled will not be able to use this feature. This is because kubelet only manages the hosts file for non-hostNetwork Pods. There are ongoing discussions to change this. + +## Why Does Kubelet Manage the Hosts File? + +kubelet [manages](https://github.com/kubernetes/kubernetes/issues/14633) the hosts file for each container of the Pod to prevent Docker from [modifying](https://github.com/moby/moby/issues/17190) the file after the containers have already been started. + +Because of the managed-nature of the file, any user-written content will be overwritten whenever the hosts file is remounted by Kubelet in the event of a container restart or a Pod reschedule. Thus, it is not suggested to modify the contents of the file. diff --git a/docs/concepts/services-networking/hostaliases-pod.yaml b/docs/concepts/services-networking/hostaliases-pod.yaml new file mode 100644 index 0000000000..aa57b9a9e5 --- /dev/null +++ b/docs/concepts/services-networking/hostaliases-pod.yaml @@ -0,0 +1,21 @@ +apiVersion: v1 +kind: Pod +metadata: + name: hostaliases-pod +spec: + hostAliases: + - ip: "127.0.0.1" + hostnames: + - "foo.local" + - "bar.local" + - ip: "10.1.2.3" + hostnames: + - "foo.remote" + - "bar.remote" + containers: + - name: cat-hosts + image: busybox + command: + - cat + args: + - "/etc/hosts"