Reorganize "Services, Load Balancing, and Networking" concept

- Add descriptions
- Change page weights

content/en/docs/concepts/cluster-administration/networking.md

@@ -14,8 +14,8 @@ problems to address:
 1. Highly-coupled container-to-container communications: this is solved by
    {{< glossary_tooltip text="Pods" term_id="pod" >}} and `localhost` communications.
 2. Pod-to-Pod communications: this is the primary focus of this document.
-3. Pod-to-Service communications: this is covered by [services](/docs/concepts/services-networking/service/).
-4. External-to-Service communications: this is covered by [services](/docs/concepts/services-networking/service/).
+3. Pod-to-Service communications: this is covered by [Services](/docs/concepts/services-networking/service/).
+4. External-to-Service communications: this is also covered by Services.
 
 <!-- body -->
 

content/en/docs/concepts/services-networking/_index.md

@@ -49,5 +49,13 @@ blind to the existence or non-existence of host ports.
 Kubernetes networking addresses four concerns:
 - Containers within a Pod [use networking to communicate](/docs/concepts/services-networking/dns-pod-service/) via loopback.
 - Cluster networking provides communication between different Pods.
-- The [Service resource](/docs/concepts/services-networking/service/) lets you [expose an application running in Pods](/docs/concepts/services-networking/connect-applications-service/) to be reachable from outside your cluster.
-- You can also use Services to [publish services only for consumption inside your cluster](/docs/concepts/services-networking/service-traffic-policy/).
+- The [Service](/docs/concepts/services-networking/service/) resource lets you
+  [expose an application running in Pods](/docs/concepts/services-networking/connect-applications-service/)
+  to be reachable from outside your cluster.
+  - [Ingress](/docs/concepts/services-networking/ingress/) provides extra functionality
+    specifically for exposing HTTP applications, websites and APIs.
+- You can also use Services to
+  [publish services only for consumption inside your cluster](/docs/concepts/services-networking/service-traffic-policy/).
+
+[Cluster Networking](/docs/concepts/cluster-administration/networking/) explains how to set
+up networking for your cluster, and also provides an overview of the technologies involved.

content/en/docs/concepts/services-networking/connect-applications-service.md

@@ -13,14 +13,12 @@ weight: 30
 
 ## The Kubernetes model for connecting containers
 
-Now that you have a continuously running, replicated application you can expose it on a network. 
+Now that you have a continuously running, replicated application you can expose it on a network.
 
 Kubernetes assumes that pods can communicate with other pods, regardless of which host they land on. Kubernetes gives every pod its own cluster-private IP address, so you do not need to explicitly create links between pods or map container ports to host ports. This means that containers within a Pod can all reach each other's ports on localhost, and all pods in a cluster can see each other without NAT. The rest of this document elaborates on how you can run reliable services on such a networking model.
 
 This guide uses a simple nginx server to demonstrate proof of concept.
 
-
-
 <!-- body -->
 
 ## Exposing pods to the cluster
@@ -53,6 +51,7 @@ kubectl get pods -l run=my-nginx -o custom-columns=POD_IP:.status.podIPs
 
 You should be able to ssh into any node in your cluster and use a tool such as `curl` to make queries against both IPs. Note that the containers are *not* using port 80 on the node, nor are there any special NAT rules to route traffic to the pod. This means you can run multiple nginx pods on the same node all using the same `containerPort`, and access them from any other pod or node in your cluster using the assigned IP address for the Service. If you want to arrange for a specific port on the host Node to be forwarded to backing Pods, you can - but the networking model should mean that you do not need to do so.
 
+
 You can read more about the [Kubernetes Networking Model](/docs/concepts/cluster-administration/networking/#the-kubernetes-network-model) if you're curious.
 
 ## Creating a Service

content/en/docs/concepts/services-networking/dns-pod-service.md

@@ -4,7 +4,10 @@ reviewers:
 - thockin
 title: DNS for Services and Pods
 content_type: concept
-weight: 20
+weight: 60
+description: >-
+  Your workload can discover Services within your cluster using DNS;
+  this page explains how that works.
 ---
 <!-- overview -->
 

content/en/docs/concepts/services-networking/dual-stack.md

@@ -1,5 +1,9 @@
 ---
 title: IPv4/IPv6 dual-stack
+description: >-
+  Kubernetes lets you configure single-stack IPv4 networking,
+  single-stack IPv6 networking, or dual stack networking with
+  both network families active. This page explains how.
 feature:
   title: IPv4/IPv6 dual-stack
   description: >

content/en/docs/concepts/services-networking/endpoint-slices.md

@@ -4,6 +4,10 @@ reviewers:
 title: EndpointSlices
 content_type: concept
 weight: 45
+description: >-
+  The EndpointSlice API is the mechanism that Kubernetes uses to let your Service
+  scale to handle large numbers of backends, and allows the cluster to update its
+  list of healthy backends efficiently.
 ---
 
 

content/en/docs/concepts/services-networking/ingress-controllers.md

@@ -1,8 +1,12 @@
 ---
 title: Ingress Controllers
-reviewers:
+description: >-
+  In order for an [Ingress](/docs/concepts/services-networking/ingress/) to work in your cluster,
+  there must be an _ingress controller_ running.
+  You need to select at least one ingress controller and make sure it is set up in your cluster.  
+  This page lists common ingress controllers that you can deploy.
 content_type: concept
-weight: 40
+weight: 30
 ---
 
 <!-- overview -->

content/en/docs/concepts/services-networking/ingress.md

@@ -3,7 +3,12 @@ reviewers:
 - bprashanth
 title: Ingress
 content_type: concept
-weight: 40
+description: >-
+  Make your HTTP (or HTTPS) network service available using a protocol-aware configuration
+  mechanism, that understands web concepts like URIs, hostnames, paths, and more.
+  The Ingress concept lets you map traffic to different backends based on rules you define
+  via the Kubernetes API.
+weight: 20
 ---
 
 <!-- overview -->

content/en/docs/concepts/services-networking/network-policies.md

@@ -6,6 +6,11 @@ reviewers:
 title: Network Policies
 content_type: concept
 weight: 50
+description: >-
+  If you want to control traffic flow at the IP address or port level (OSI layer 3 or 4),
+  NetworkPolicies allow you to specify rules for traffic flow within your cluster, and
+  also between Pods and the outside world.
+  Your cluster must use a network plugin that supports NetworkPolicy enforcement.
 ---
 
 <!-- overview -->

content/en/docs/concepts/services-networking/service-traffic-policy.md

@@ -3,7 +3,12 @@ reviewers:
 - maplain
 title: Service Internal Traffic Policy
 content_type: concept
-weight: 45
+weight: 75
+description: >-
+  If two Pods in your cluster want to communicate, and both Pods are actually running on
+  the same node, _Service Internal Traffic Policy_ to keep network traffic within that node.
+  Avoiding a round trip via the cluster network can help with reliability, performance
+  (network latency and throughput), or cost.
 ---
 
 
@@ -23,7 +28,7 @@ cluster. This can help to reduce costs and improve performance.
 The `ServiceInternalTrafficPolicy` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
 is a Beta feature and enabled by default.
 When the feature is enabled, you can enable the internal-only traffic policy for a
-{{< glossary_tooltip text="Services" term_id="service" >}}, by setting its
+{{< glossary_tooltip text="Service" term_id="service" >}}, by setting its
 `.spec.internalTrafficPolicy` to `Local`.
 This tells kube-proxy to only use node local endpoints for cluster internal traffic.
 

content/en/docs/concepts/services-networking/service.md

@@ -6,7 +6,9 @@ feature:
   title: Service discovery and load balancing
   description: >
     No need to modify your application to use an unfamiliar service discovery mechanism. Kubernetes gives Pods their own IP addresses and a single DNS name for a set of Pods, and can load-balance across them.
-
+description: >-
+  Expose an application running in your cluster behind a single outward-facing
+  endpoint, even when the workload is split across multiple backends.
 content_type: concept
 weight: 10
 ---

content/en/docs/concepts/services-networking/topology-aware-hints.md

@@ -3,7 +3,11 @@ reviewers:
 - robscott
 title: Topology Aware Hints
 content_type: concept
-weight: 45
+weight: 70
+description: >-
+  _Topology Aware Hints_ provides a mechanism to help keep network traffic within the zone
+  where it originated. Preferring same-zone traffic between Pods in your cluster can help
+  with reliability, performance (network latency and throughput), or cost.
 ---