From f5be3eba118fc2907cd70fb88d3188120cf66d96 Mon Sep 17 00:00:00 2001 From: bmcelvee Date: Mon, 21 Jan 2019 12:57:19 -0500 Subject: [PATCH] OSDOCS-52 Understanding Networking --- _topic_map.yml | 8 ++- modules/networking-ne-openshift-dns.adoc | 73 ++++++++++++++++++++++++ networking/understanding-networking.adoc | 20 +++++++ 3 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 modules/networking-ne-openshift-dns.adoc create mode 100644 networking/understanding-networking.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 9a1b825355..fbf651ef53 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -63,7 +63,7 @@ Distros: openshift-* Topics: - Name: Architecture File: architecture ---- +--- Name: Authentication Dir: authentication Distros: openshift-* @@ -113,8 +113,8 @@ Topics: File: using-service-accounts-as-oauth-client - Name: Scoping tokens File: tokens-scoping -- Name: Managing Security Context Constraints - File: managing-security-context-constraints +- Name: Managing Security Context Constraints + File: managing-security-context-constraints --- Name: Users and roles Dir: users_and_roles @@ -140,6 +140,8 @@ Name: Networking Dir: networking Distros: openshift-* Topics: +- Name: Understanding networking + File: understanding-networking - Name: Using cookies to keep route statefulness File: using-cookies-to-keep-route-statefulness --- diff --git a/modules/networking-ne-openshift-dns.adoc b/modules/networking-ne-openshift-dns.adoc new file mode 100644 index 0000000000..9e4cb40118 --- /dev/null +++ b/modules/networking-ne-openshift-dns.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// * assembly/networking + +[id='networking-ne-openshift-dns-{context}'] += {product-title} DNS + +If you are running multiple services, such as frontend and backend services for +use with multiple pods, environment variables are created for user names, +service IPs, and more so the frontend pods can communicate with the backend +services. If the service is deleted and recreated, a new IP address can be +assigned to the service, and requires the frontend pods to be recreated to pick +up the updated values for the service IP environment variable. Additionally, the +backend service has to be created before any of the frontend pods to ensure that +the service IP is generated properly, and that it can be provided to the +frontend pods as an environment variable. + +For this reason, {product-title} has a built-in DNS so that the services can be +reached by the service DNS as well as the service IP/port. {product-title} +supports split DNS by running SkyDNS on the master that answers +DNS queries for services. The master listens to port 53 by default. + +When the node starts, the following message indicates the Kubelet is correctly +resolved to the master: + +---- +0308 19:51:03.118430 4484 node.go:197] Started Kubelet for node +openshiftdev.local, server at 0.0.0.0:10250 +I0308 19:51:03.118459 4484 node.go:199] Kubelet is setting 10.0.2.15 as a +DNS nameserver for domain "local" +---- + +If the second message does not appear, the Kubernetes service may not be available. + +On a node host, each container's nameserver has the master name added to the +front, and the default search domain for the container will be +`.__.cluster.local`. The container will then direct any +nameserver queries to the master before any other nameservers on the node, which +is the default behavior for Docker-formatted containers. The master will answer +queries on the `.cluster.local` domain that have the following form: + +.DNS Example Names +[cols=".2,.^5,8",options="header"] +|=== + +|Object Type |Example + +|Default +|.cluster.local + +|Services +|..svc.cluster.local + +|Endpoints +|..endpoints.cluster.local +|=== + +This prevents having to restart frontend pods in order to pick up new services, +which would create a new IP for the service. This also removes the need to use +environment variables, because pods can use the service DNS. Also, as the DNS +does not change, you can reference database services as `db.local` in +configuration files. Wildcard lookups are also supported, because any lookups +resolve to the service IP, and removes the need to create the backend service +before any of the frontend pods, since the service name (and hence DNS) is +established upfront. + +This DNS structure also covers headless services, where a portal IP is not +assigned to the service and the kube-proxy does not load-balance or provide +routing for its endpoints. Service DNS can still be used and responds with +multiple A records, one for each pod of the service, allowing the client to +round-robin between each pod. + +.Additional resources +* link:https://github.com/skynetservices/skydns[SkyDNS] diff --git a/networking/understanding-networking.adoc b/networking/understanding-networking.adoc new file mode 100644 index 0000000000..265d34fb42 --- /dev/null +++ b/networking/understanding-networking.adoc @@ -0,0 +1,20 @@ +[id='understanding-networking'] += Understanding networking +include::modules/common-attributes.adoc[] +:context: understanding-networking + +toc::[] + +Kubernetes ensures that pods are able to network with each other, and +allocates each pod an IP address from an internal network. This ensures all +containers within the pod behave as if they were on the same host. Giving each +pod its own IP address means that pods can be treated like physical hosts or +virtual machines in terms of port allocation, networking, naming, service +discovery, load balancing, application configuration, and migration. + +Creating links between pods is unnecessary, and it is not recommended that +your pods talk to one another directly using the IP address. Instead, it is +recommend that you create a service, then interact +with the service. + +include::modules/networking-ne-openshift-dns.adoc[leveloffset=+1]