OSDOCS-52 Understanding Networking

_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
 ---

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
+`._<pod_namespace>_.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
+|<pod_namespace>.cluster.local
+
+|Services
+|<service>.<pod_namespace>.svc.cluster.local
+
+|Endpoints
+|<name>.<namespace>.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]

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]